POST
/
conversations
Create a conversation
curl --request POST \
  --url https://api.operator.xyz/conversations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Operator-Version: <operator-version>' \
  --data '{
  "agent_id": "<string>",
  "channel": {
    "type": "phone",
    "callee_no": "<string>",
    "caller_no": null,
    "priority": "normal"
  }
}'
{
  "id": "<string>",
  "channel": {
    "type": "phone",
    "callee_no": null,
    "caller_no": null,
    "token": "<string>",
    "events_url": "<string>"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Operator-Version
enum<string>
required

The API version to use.

Available options:
2025-06-19

Body

application/json
​
agent_id
string
required

The agent that should handle the conversation. Use ca_8qm9JBCiTe7 for the released version or ca_8qm9JBCiTe7@v2 for a specific version.

​
channel
object
required

Configuration for the channel the conversation will be created on. Parameters for creating a phone channel conversation.

​
livemode
boolean
default:true

Whether the conversation should be created in live mode.

​
override_config
object

Partial override for the agent's configuration (e.g. voice, runtime, tools). Follows the same shape as the agent configuration object, but all fields are optional since it is merged into the base config.

Read more on dynamic configuration.

​
context
object

Arbitrary context passed to the agent. This can include runtime variable values, user metadata, or any other relevant payload.

Response

Successful response.

​
id
string
required

Unique identifier for the conversation, e.g. conv_8qm9JBCiTe7.

​
channel
object
required

Details of the channel the conversation was created on. Will match the type of the channel used in the request. Response object for creating a phone channel conversation.