Skip to main content
POST
/
v1
/
chat
/
session
Create a chat session
curl --request POST \
  --url https://api.osvi.ai/v1/chat/session \
  --header 'API-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_uuid": "agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og",
  "customer_id": "+15551112222",
  "input_fields": {
    "first_name": "Alex"
  },
  "context": [
    "Initial context for this chat"
  ]
}
'
{
  "success": true,
  "data": {
    "id": "4718a326-417b-4dda-90d0-21fd65a11cb8",
    "chat_agent_id": 42,
    "account_id": 7,
    "customer_id": "+15551112222",
    "mode": "ai",
    "help_requested": false,
    "status": "active",
    "current_state": null,
    "metadata": {
      "input_fields": {
        "first_name": "Alex"
      },
      "state_fields": {},
      "context": [
        "Initial context for this chat"
      ]
    },
    "active_human": null,
    "created_at": "2026-06-04T11:40:25.690486Z",
    "updated_at": "2026-06-04T11:40:25.690486Z"
  }
}

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 OSVI agent to chat with. Must be an active, non-archived agent belonging to the account that owns the API token.

Example:

"agent_IsZ3Q6Sf_60Eh26XQMGbz-R_og"

​
customer_id
string
required

Your identifier for the customer on the other side of the conversation — typically a phone number, but any stable string works. Used to resolve the active session on subsequent messages.

Example:

"+15551112222"

​
input_fields
object

Arbitrary key-value object describing the customer, made available to the agent at runtime (e.g. name, account tier).

Example:
{ "first_name": "Alex" }
​
context
string[]

Initial free-text context entries for the session. Only the most recent 5 non-empty strings are retained (FIFO). Append more later with the inject-context endpoint.

Example:
["Initial context for this chat"]

Response

Session created successfully

​
success
boolean
Example:

true

​
data
object

A chat session record.