SDK API
REST API endpoints used by the SDK
Overview
These endpoints are called by the SDK to establish voice sessions and send text messages. Authentication is via agent_token in the request body.
Base URL: https://api.chans.ai (managed) or your self-hosted endpoint.
Create Voice Session
Establishes a real-time voice session. The SDK calls this automatically when you call connect().
POST /sdk/v1/session
Request:
{ "agent_token": "agt_xxx", "user_id": "optional-user-123"}
| Field | Type | Required | Description |
|---|---|---|---|
agent_token | string | Yes | Agent token from dashboard |
user_id | string | No | User identifier for conversation segmentation |
Response:
{ "session_id": "room_abc123_def456", "connection_token": "eyJ...", "connection_url": "wss://livekit.example.com"}
| Field | Type | Description |
|---|---|---|
session_id | string | Unique session identifier |
connection_token | string | LiveKit JWT token (used internally by SDK) |
connection_url | string | LiveKit WebSocket URL (used internally by SDK) |
Errors:
| Status | Description |
|---|---|
| 401 | Invalid agent token |
| 429 | Rate limit exceeded |
| 503 | Voice service not configured |
Text Chat
Send a text message to an agent and get a text response. Useful for testing agents without voice or building text-based interfaces.
POST /sdk/v1/chat
Request:
{ "agent_token": "agt_xxx", "message": "What's my order status?", "session_id": "optional-existing-session", "user_id": "optional-user-123"}
| Field | Type | Required | Description |
|---|---|---|---|
agent_token | string | Yes | Agent token from dashboard |
message | string | Yes | Text message to send |
session_id | string | No | Continue an existing session |
user_id | string | No | User identifier |
Response:
{ "session_id": "chat_abc123_def456", "response": "Your order #1234 is out for delivery!", "mode": "enhanced"}
| Field | Type | Description |
|---|---|---|
session_id | string | Session identifier (reuse to continue conversation) |
response | string | Agent's text response |
mode | string | Agent mode used ("enhanced" or "passthrough") |
Errors:
| Status | Description |
|---|---|
| 400 | Passthrough mode requires webhook_url |
| 401 | Invalid agent token |
| 429 | Rate limit exceeded |
| 502 | LLM call or webhook failed |
Example: Text Chat with curl
curl -X POST https://api.chans.ai/sdk/v1/chat \ -H "Content-Type: application/json" \ -d '{ "agent_token": "agt_xxx", "message": "Hello, what can you help me with?" }'