Send Message
Send a message to an agent and receive a response.
POST
/chatSend a message to an agent. Returns the agent's complete response.
No parameters for this endpoint.
Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
agent_id | string | Yes | — | Target agent ID (ag_*) |
message | string | Yes | — | User message text |
session_id | string | No | Auto-generated | Session ID for conversation memory. Reuse to continue a conversation |
stream | boolean | No | false | Enable streaming response (use Stream endpoint instead) |
metadata | object | No | null | Additional context passed to the agent (e.g., user info, page URL) |
Response 200
{
"response": "Our business hours are Monday through Friday, 9 AM to 6 PM EST. We're also available on Saturdays from 10 AM to 2 PM.",
"session_id": "sess_customer_001",
"usage": {
"input_tokens": 45,
"output_tokens": 32,
"total_tokens": 77
},
"tool_calls": []
}Response Fields
| Field | Type | Description |
|---|---|---|
response | string | Agent's text response |
session_id | string | Session ID — reuse for follow-up messages |
usage.input_tokens | integer | Tokens consumed by the prompt |
usage.output_tokens | integer | Tokens in the agent's response |
usage.total_tokens | integer | Total tokens consumed (billed) |
tool_calls | array | Tools the agent invoked during this response |
Example with Metadata
{
"agent_id": "ag_c47e7c97_b2f2",
"message": "I need help with my order",
"session_id": "sess_customer_001",
"metadata": {
"user_name": "Jane Doe",
"user_email": "jane@example.com",
"page_url": "https://store.example.com/orders/12345"
}
}Errors
| Code | Description |
|---|---|
401 | Missing or invalid authentication |
402 | Insufficient balance |
404 | Agent not found |
429 | Rate limit exceeded |