Skip to main content
POST
/
v1
/
agents
/
{agent_id}
/
gateway
/
conversations
/
{conversation_id}
/
messages
Send Conversation Message
curl --request POST \
  --url https://api.xpander.ai/v1/agents/{agent_id}/gateway/conversations/{conversation_id}/messages \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "text": "",
  "files": [
    "<string>"
  ],
  "mode": "auto",
  "idempotency_key": "<string>",
  "user": {}
}
'
{
  "action": "<string>",
  "message_id": "<string>",
  "queue_depth": 0,
  "steer_target": "<string>"
}
mode=auto queues the message while a turn is running and signals started when the conversation is idle; mode=queue always enqueues. A started response means the message was not enqueued (queue_depth: 0) - the conversation is idle, so run the turn yourself with Run Gateway Turn passing id = conversation_id. A queued response means it was enqueued behind a running turn; that turn drains it automatically, or if nothing is streaming you run the queue with Drain Queue. See the Agent Gateway overview for the full conversation model.

Authorizations

​
x-api-key
string
header
required

API Key for authentication

Path Parameters

​
agent_id
string
required
​
conversation_id
string
required

Body

application/json

Body of the chat-backend messages / steer endpoints.

​
text
string
default:""
​
files
string[]
​
mode
enum<string>
default:auto

How an inbound message to a (possibly running) conversation is handled.

Available options:
auto,
queue,
steer
​
idempotency_key
string | null
​
user
User · object

Response

Successful Response

Result of accepting an inbound message for a running conversation.

​
action
string
required
​
message_id
string | null
​
queue_depth
integer
default:0
​
steer_target
string | null