Send a chat message (async)

curl --request POST \
  --url https://api.osvi.ai/v1/chat/inbound/async \
  --header 'API-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_uuid": "agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og",
  "customer_id": "+15551112222",
  "content": "Hi, I need help.",
  "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
  "idempotency_key": "wh-2f8a1c-attempt-1",
  "input_fields": {
    "first_name": "Alex"
  },
  "state_fields": {},
  "context": [
    "Customer called in about a refund yesterday."
  ],
  "type": "message",
  "interaction_id": "b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10",
  "option_id": "opt_confirm",
  "response": {
    "kind": "selection",
    "value": "opt_confirm"
  },
  "supported_interactions": [
    {
      "tool_type": "ui_buttons",
      "schema_version": 2
    }
  ]
}
'

import requests

url = "https://api.osvi.ai/v1/chat/inbound/async"

payload = {
    "agent_uuid": "agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og",
    "customer_id": "+15551112222",
    "content": "Hi, I need help.",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
    "idempotency_key": "wh-2f8a1c-attempt-1",
    "input_fields": { "first_name": "Alex" },
    "state_fields": {},
    "context": ["Customer called in about a refund yesterday."],
    "type": "message",
    "interaction_id": "b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10",
    "option_id": "opt_confirm",
    "response": {
        "kind": "selection",
        "value": "opt_confirm"
    },
    "supported_interactions": [
        {
            "tool_type": "ui_buttons",
            "schema_version": 2
        }
    ]
}
headers = {
    "API-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'API-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_uuid: 'agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og',
    customer_id: '+15551112222',
    content: 'Hi, I need help.',
    session_id: '4718a326-417b-4dda-90d0-21fd65a11cb8',
    idempotency_key: 'wh-2f8a1c-attempt-1',
    input_fields: {first_name: 'Alex'},
    state_fields: {},
    context: ['Customer called in about a refund yesterday.'],
    type: 'message',
    interaction_id: 'b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10',
    option_id: 'opt_confirm',
    response: {kind: 'selection', value: 'opt_confirm'},
    supported_interactions: [{tool_type: 'ui_buttons', schema_version: 2}]
  })
};

fetch('https://api.osvi.ai/v1/chat/inbound/async', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.osvi.ai/v1/chat/inbound/async",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_uuid' => 'agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og',
    'customer_id' => '+15551112222',
    'content' => 'Hi, I need help.',
    'session_id' => '4718a326-417b-4dda-90d0-21fd65a11cb8',
    'idempotency_key' => 'wh-2f8a1c-attempt-1',
    'input_fields' => [
        'first_name' => 'Alex'
    ],
    'state_fields' => [
        
    ],
    'context' => [
        'Customer called in about a refund yesterday.'
    ],
    'type' => 'message',
    'interaction_id' => 'b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10',
    'option_id' => 'opt_confirm',
    'response' => [
        'kind' => 'selection',
        'value' => 'opt_confirm'
    ],
    'supported_interactions' => [
        [
                'tool_type' => 'ui_buttons',
                'schema_version' => 2
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Token: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.osvi.ai/v1/chat/inbound/async"

	payload := strings.NewReader("{\n  \"agent_uuid\": \"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og\",\n  \"customer_id\": \"+15551112222\",\n  \"content\": \"Hi, I need help.\",\n  \"session_id\": \"4718a326-417b-4dda-90d0-21fd65a11cb8\",\n  \"idempotency_key\": \"wh-2f8a1c-attempt-1\",\n  \"input_fields\": {\n    \"first_name\": \"Alex\"\n  },\n  \"state_fields\": {},\n  \"context\": [\n    \"Customer called in about a refund yesterday.\"\n  ],\n  \"type\": \"message\",\n  \"interaction_id\": \"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10\",\n  \"option_id\": \"opt_confirm\",\n  \"response\": {\n    \"kind\": \"selection\",\n    \"value\": \"opt_confirm\"\n  },\n  \"supported_interactions\": [\n    {\n      \"tool_type\": \"ui_buttons\",\n      \"schema_version\": 2\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("API-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.osvi.ai/v1/chat/inbound/async")
  .header("API-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_uuid\": \"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og\",\n  \"customer_id\": \"+15551112222\",\n  \"content\": \"Hi, I need help.\",\n  \"session_id\": \"4718a326-417b-4dda-90d0-21fd65a11cb8\",\n  \"idempotency_key\": \"wh-2f8a1c-attempt-1\",\n  \"input_fields\": {\n    \"first_name\": \"Alex\"\n  },\n  \"state_fields\": {},\n  \"context\": [\n    \"Customer called in about a refund yesterday.\"\n  ],\n  \"type\": \"message\",\n  \"interaction_id\": \"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10\",\n  \"option_id\": \"opt_confirm\",\n  \"response\": {\n    \"kind\": \"selection\",\n    \"value\": \"opt_confirm\"\n  },\n  \"supported_interactions\": [\n    {\n      \"tool_type\": \"ui_buttons\",\n      \"schema_version\": 2\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.osvi.ai/v1/chat/inbound/async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["API-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_uuid\": \"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og\",\n  \"customer_id\": \"+15551112222\",\n  \"content\": \"Hi, I need help.\",\n  \"session_id\": \"4718a326-417b-4dda-90d0-21fd65a11cb8\",\n  \"idempotency_key\": \"wh-2f8a1c-attempt-1\",\n  \"input_fields\": {\n    \"first_name\": \"Alex\"\n  },\n  \"state_fields\": {},\n  \"context\": [\n    \"Customer called in about a refund yesterday.\"\n  ],\n  \"type\": \"message\",\n  \"interaction_id\": \"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10\",\n  \"option_id\": \"opt_confirm\",\n  \"response\": {\n    \"kind\": \"selection\",\n    \"value\": \"opt_confirm\"\n  },\n  \"supported_interactions\": [\n    {\n      \"tool_type\": \"ui_buttons\",\n      \"schema_version\": 2\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "accepted": true,
  "data": {
    "state": "accepted",
    "turn_id": "turn_9f3d2a1b",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
    "idempotency_key": "wh-2f8a1c-attempt-1"
  }
}

{
  "success": false,
  "error": "agent_not_found"
}

{
  "success": false,
  "error": "agent_not_found"
}

{
  "success": false,
  "error": "agent_not_found"
}

{
  "success": false,
  "error": "idempotency_key_reused",
  "data": {
    "state": "error",
    "turn_id": "turn_9f3d2a1b",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8"
  }
}

{
  "success": false,
  "error": "idempotency_key_reused",
  "data": {
    "state": "error",
    "turn_id": "turn_9f3d2a1b",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8"
  }
}

{
  "success": false,
  "error": "Python engine returned 422 for POST /v1/chat/session/{id}/support",
  "upstream_body": {
    "state": "rejected",
    "reason": "tell_not_allowed_during_takeover"
  }
}

Chat

Send Message (Async)

Accepts an inbound customer message and answers immediately without waiting for the agent’s reply. Every reply — and the turn’s completion — is delivered to the agent’s delivery URL instead of riding back on this response.

Requires the agent to have a delivery URL configured; use this endpoint when your integration can’t hold a request open for the length of a turn (e.g. a webhook-based gateway with its own timeout). Otherwise, Send Message is simpler.

Takes the same parameters as Send Message, including idempotency_key, interactive-message fields, and supported_interactions.

POST

chat

inbound

async

Send a chat message (async)

curl --request POST \
  --url https://api.osvi.ai/v1/chat/inbound/async \
  --header 'API-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_uuid": "agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og",
  "customer_id": "+15551112222",
  "content": "Hi, I need help.",
  "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
  "idempotency_key": "wh-2f8a1c-attempt-1",
  "input_fields": {
    "first_name": "Alex"
  },
  "state_fields": {},
  "context": [
    "Customer called in about a refund yesterday."
  ],
  "type": "message",
  "interaction_id": "b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10",
  "option_id": "opt_confirm",
  "response": {
    "kind": "selection",
    "value": "opt_confirm"
  },
  "supported_interactions": [
    {
      "tool_type": "ui_buttons",
      "schema_version": 2
    }
  ]
}
'

import requests

url = "https://api.osvi.ai/v1/chat/inbound/async"

payload = {
    "agent_uuid": "agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og",
    "customer_id": "+15551112222",
    "content": "Hi, I need help.",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
    "idempotency_key": "wh-2f8a1c-attempt-1",
    "input_fields": { "first_name": "Alex" },
    "state_fields": {},
    "context": ["Customer called in about a refund yesterday."],
    "type": "message",
    "interaction_id": "b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10",
    "option_id": "opt_confirm",
    "response": {
        "kind": "selection",
        "value": "opt_confirm"
    },
    "supported_interactions": [
        {
            "tool_type": "ui_buttons",
            "schema_version": 2
        }
    ]
}
headers = {
    "API-Token": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'API-Token': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_uuid: 'agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og',
    customer_id: '+15551112222',
    content: 'Hi, I need help.',
    session_id: '4718a326-417b-4dda-90d0-21fd65a11cb8',
    idempotency_key: 'wh-2f8a1c-attempt-1',
    input_fields: {first_name: 'Alex'},
    state_fields: {},
    context: ['Customer called in about a refund yesterday.'],
    type: 'message',
    interaction_id: 'b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10',
    option_id: 'opt_confirm',
    response: {kind: 'selection', value: 'opt_confirm'},
    supported_interactions: [{tool_type: 'ui_buttons', schema_version: 2}]
  })
};

fetch('https://api.osvi.ai/v1/chat/inbound/async', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.osvi.ai/v1/chat/inbound/async",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_uuid' => 'agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og',
    'customer_id' => '+15551112222',
    'content' => 'Hi, I need help.',
    'session_id' => '4718a326-417b-4dda-90d0-21fd65a11cb8',
    'idempotency_key' => 'wh-2f8a1c-attempt-1',
    'input_fields' => [
        'first_name' => 'Alex'
    ],
    'state_fields' => [
        
    ],
    'context' => [
        'Customer called in about a refund yesterday.'
    ],
    'type' => 'message',
    'interaction_id' => 'b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10',
    'option_id' => 'opt_confirm',
    'response' => [
        'kind' => 'selection',
        'value' => 'opt_confirm'
    ],
    'supported_interactions' => [
        [
                'tool_type' => 'ui_buttons',
                'schema_version' => 2
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "API-Token: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.osvi.ai/v1/chat/inbound/async"

	payload := strings.NewReader("{\n  \"agent_uuid\": \"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og\",\n  \"customer_id\": \"+15551112222\",\n  \"content\": \"Hi, I need help.\",\n  \"session_id\": \"4718a326-417b-4dda-90d0-21fd65a11cb8\",\n  \"idempotency_key\": \"wh-2f8a1c-attempt-1\",\n  \"input_fields\": {\n    \"first_name\": \"Alex\"\n  },\n  \"state_fields\": {},\n  \"context\": [\n    \"Customer called in about a refund yesterday.\"\n  ],\n  \"type\": \"message\",\n  \"interaction_id\": \"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10\",\n  \"option_id\": \"opt_confirm\",\n  \"response\": {\n    \"kind\": \"selection\",\n    \"value\": \"opt_confirm\"\n  },\n  \"supported_interactions\": [\n    {\n      \"tool_type\": \"ui_buttons\",\n      \"schema_version\": 2\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("API-Token", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.osvi.ai/v1/chat/inbound/async")
  .header("API-Token", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_uuid\": \"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og\",\n  \"customer_id\": \"+15551112222\",\n  \"content\": \"Hi, I need help.\",\n  \"session_id\": \"4718a326-417b-4dda-90d0-21fd65a11cb8\",\n  \"idempotency_key\": \"wh-2f8a1c-attempt-1\",\n  \"input_fields\": {\n    \"first_name\": \"Alex\"\n  },\n  \"state_fields\": {},\n  \"context\": [\n    \"Customer called in about a refund yesterday.\"\n  ],\n  \"type\": \"message\",\n  \"interaction_id\": \"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10\",\n  \"option_id\": \"opt_confirm\",\n  \"response\": {\n    \"kind\": \"selection\",\n    \"value\": \"opt_confirm\"\n  },\n  \"supported_interactions\": [\n    {\n      \"tool_type\": \"ui_buttons\",\n      \"schema_version\": 2\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.osvi.ai/v1/chat/inbound/async")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["API-Token"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_uuid\": \"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og\",\n  \"customer_id\": \"+15551112222\",\n  \"content\": \"Hi, I need help.\",\n  \"session_id\": \"4718a326-417b-4dda-90d0-21fd65a11cb8\",\n  \"idempotency_key\": \"wh-2f8a1c-attempt-1\",\n  \"input_fields\": {\n    \"first_name\": \"Alex\"\n  },\n  \"state_fields\": {},\n  \"context\": [\n    \"Customer called in about a refund yesterday.\"\n  ],\n  \"type\": \"message\",\n  \"interaction_id\": \"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10\",\n  \"option_id\": \"opt_confirm\",\n  \"response\": {\n    \"kind\": \"selection\",\n    \"value\": \"opt_confirm\"\n  },\n  \"supported_interactions\": [\n    {\n      \"tool_type\": \"ui_buttons\",\n      \"schema_version\": 2\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "success": true,
  "accepted": true,
  "data": {
    "state": "accepted",
    "turn_id": "turn_9f3d2a1b",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
    "idempotency_key": "wh-2f8a1c-attempt-1"
  }
}

{
  "success": false,
  "error": "agent_not_found"
}

{
  "success": false,
  "error": "agent_not_found"
}

{
  "success": false,
  "error": "agent_not_found"
}

{
  "success": false,
  "error": "idempotency_key_reused",
  "data": {
    "state": "error",
    "turn_id": "turn_9f3d2a1b",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8"
  }
}

{
  "success": false,
  "error": "idempotency_key_reused",
  "data": {
    "state": "error",
    "turn_id": "turn_9f3d2a1b",
    "session_id": "4718a326-417b-4dda-90d0-21fd65a11cb8"
  }
}

{
  "success": false,
  "error": "Python engine returned 422 for POST /v1/chat/session/{id}/support",
  "upstream_body": {
    "state": "rejected",
    "reason": "tell_not_allowed_during_takeover"
  }
}

Authorizations

API-Token

string

header

required

16-character API token associated with your OSVI account. Find it in your dashboard under Settings → API.

Body

application/json

agent_uuid

string

required

Unique identifier of the agent handling the conversation.

Example:

"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og"

customer_id

string

required

Your identifier for the customer sending the message. Used to resolve the active session when session_id is omitted.

Example:

"+15551112222"

content

string

The customer's message text. Required unless type is interaction_response.

Example:

"Hi, I need help."

session_id

string

Optional session UUID to route the message to. If omitted, the engine resolves the active/new session for the customer + agent.

Example:

"4718a326-417b-4dda-90d0-21fd65a11cb8"

idempotency_key

string

Your identifier for this exact turn. Strongly recommended on this endpoint: since the reply arrives later on the delivery webhook, this is what lets you correlate it back to the request that triggered it (it's echoed on every delivered envelope). A retry with the same key returns the original 202 instead of accepting the turn twice. Can also be sent as an Idempotency-Key header instead of a body field.

Example:

"wh-2f8a1c-attempt-1"

input_fields

object

Arbitrary key-value object made available to the agent at runtime. Only applied when this request creates a new session.

Example:

{ "first_name": "Alex" }

state_fields

object

Initial values for the agent's configured state fields. Only applied when this request creates a new session.

Example:

{}

context

string[]

Free-text context entries for a newly created session. Only the most recent 5 non-empty strings are retained. Only applied when this request creates a new session.

Example:

[
  "Customer called in about a refund yesterday."
]

type

enum<string>

default:message

message for a normal text message (default). interaction_response to answer an interactive message the agent sent — see Interactive messages.

Available options:

message,

interaction_response

Example:

"message"

interaction_id

string<uuid>

Required when type is interaction_response.

Example:

"b6a3e6c2-2d61-4a4b-9c9a-5a2d9f6a2b10"

option_id

string

Shorthand answer for a simple option tap. Send this or response, not both.

Example:

"opt_confirm"

response

object

Structured answer to a pending interactive message. Send this or option_id, never both. See Interactive messages.

Show child attributes

supported_interactions

object[]

Declares which interactive message types your client can render. See Interactive messages.

Show child attributes

Response

Turn accepted. The reply (and every other reply this turn produces) is delivered to the chat delivery webhook, not in this response.

success

boolean

Example:

true

accepted

boolean

Example:

true

data

object

Show child attributes

Get Started

Going Deeper

API Reference

Send Message (Async)

Authorizations

Body

Response