Chat Sessions API
A chat session is a single conversation between a chatbot and a contact, persisted with full message history.
Endpoints
| Method | Path | Description |
|---|---|---|
| GET | `/api/v1/chat-sessions` | List (filter by botId / status) |
| GET | `/api/v1/chat-sessions/:id` | Get with messages |
| POST | `/api/v1/chat-sessions/:id/takeover` | Switch to human takeover |
| POST | `/api/v1/chat-sessions/:id/messages` | Send a message (as bot or human) |
| POST | `/api/v1/chat-sessions/:id/close` | Close the session |
Schema
{
"id": "ses_01H...",
"tenantId": "tnt_01H...",
"botId": "bot_01H...",
"contactId": "ctc_01H...",
"status": "ACTIVE",
"startedAt": "2026-05-04T08:00:00Z",
"endedAt": null,
"rating": null
}Takeover
When a bot triggers a handoff, the session moves to HUMAN_TAKEOVER. Subsequent /messages calls are attributed to the calling user.
Every response uses the standard envelope:
{
"success": true,
"data": { /* resource or array */ },
"meta": { "total": 100, "cursor": "...", "hasMore": true },
"error": { "code": "ERROR_CODE", "message": "Human readable" }
}error is omitted on success; meta is omitted when not paginating.
Rate Limits
Subject to the standard 200 req/min/tenant authenticated limit. See [Rate Limits](/docs/api-reference/rate-limits) for full details and the per-endpoint overrides.