> For the full page index, fetch https://echonova.ai/llms.txt # Start a live session with an agent Starts a voice or chat session, as the portal's Test button does, and returns a room token and address. The token is sent only in this response: join the room with it from your client, and end the session with POST /v1/agents/{agentId}/sessions/{sessionId}/end. Uses workspace credits, which do not count against this key's credit limit, and the agent's own chat and call limits apply. A retried start opens a second session. Needs the agents:talk scope on the key. ## Endpoint `POST https://api.echonova.ai/v1/agents/{agentId}/sessions` ## Authentication Keys are created in the portal under Developers, sent as `Authorization: Bearer YOUR_API_KEY`. See [Get an API key](/docs/developers/get-an-api-key). ## Request | Name | In | Type | Required | Limits | Description | | ------- | ---- | ------------- | -------- | ----------------------------------- | -------------------------------------------------------------------------------------------------- | | agentId | path | string | Yes | | The agent id, as GET /v1/agents returned it. | | channel | body | voice \| chat | No | one of voice, chat, default "voice" | voice opens a room you join with the returned token; chat opens a text session. Defaults to voice. | ## Responses | Status | Description | | ------ | ---------------------- | | 200 | OK | | 400 | Bad Request | | 401 | Unauthorized | | 402 | Payment Required | | 403 | Forbidden | | 404 | Not Found | | 409 | Conflict | | 413 | Payload Too Large | | 415 | Unsupported Media Type | | 429 | Too Many Requests | | 500 | Internal Server Error | | 503 | Service Unavailable | | 504 | Gateway Timeout | ## Response A success answers 200 with the envelope `{ data, success, statusCode, errorMessage }`. The `data` fields: | Field | Type | Description | | --------- | ------ | ----------------------------------------------------------------------------------------------------------------- | | id | string | The session id; also the conversation id once it ends. | | agentId | string | The agent id. | | channel | string | voice for a room you speak in, chat for a text session. | | status | string | active while it is open; ended after you end it or it finishes; failed or out_of_credits when it stopped early. | | startedAt | string | When it started, as an ISO 8601 date-time. | | endedAt | string | When it ended; null while it is open. | | token | string | The room token. It is sent once, here, and never again: keep it secret and hand it only to the client that joins. | | wsUrl | string | The room address the client connects to with the token. | | greeting | string | A chat session's first agent message, to show before the agent speaks; null for voice. | ```json { "data": { "id": "6651a1b2c3d4e5f6a7b8c9d0", "agentId": "6650a1b2c3d4e5f6a7b8c9d0", "channel": "voice", "status": "active", "startedAt": "2026-11-07T10:00:00.000Z", "endedAt": null, "token": "eyJhbGciOi...", "wsUrl": "wss://rooms.echonova.ai", "greeting": "Hello! How can I help?" }, "success": true, "statusCode": 200, "errorMessage": null } ``` ## Errors | Status | errorMessage | When | Fix | | ------ | ------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | | 400 | Invalid identifier | agentId or sessionId is not a 24-character hexadecimal id. | Use the id exactly as GET /v1/agents returned it. | | 400 | channel must be one of the following values: voice, chat | channel is sent and is neither voice nor chat. | Send voice or chat, or leave channel out for voice. | | 400 | property should not exist | The body or query carries a field the endpoint does not define. | Remove the field. | | 401 | Unauthorized | The Authorization header is missing or is not Bearer ek\_..., no key matches the token, or the key is deleted, disabled or its account is closed. | Send Authorization: Bearer ek\_... with an enabled key from this environment. | | 402 | Out of credits. Top up your plan to start a voice session. | The workspace has no credits left to start a voice session; nothing was charged. | Add credits to the workspace. | | 402 | Out of credits. Top up your plan to start a chat session. | The workspace has no credits left to start a chat session; nothing was charged. | Add credits to the workspace. | | 402 | Your trial AI allowance is used up. Upgrade to keep using AI. | The workspace is on a trial and its AI allowance is used up; nothing ran and nothing was charged. | Upgrade the plan. | | 403 | Subscription not found | The workspace that owns the key has no subscription. | Check the workspace's plan in the portal. | | 403 | Subscription expired or inactive | The subscription is in a state other than active or trial. | Renew the subscription. | | 403 | This API key cannot talk to agents. | The key does not have the agents:talk scope. | Edit the key and give it the agents:talk scope, or use another key. | | 403 | The member who created this API key cannot view agents. | The member who created the key has left the workspace, or no longer has both the View agents and Manage developer API permissions. It is checked on every call. | Give that member both permissions again, or create a key as a member who has them. | | 403 | Workspace is not active | The workspace is closed; nothing ran and nothing was charged. | Contact support to reopen the workspace. | | 403 | Subscription has expired | The subscription has expired and no bought credits are left; nothing ran and nothing was charged. | Renew the subscription or buy credits. | | 404 | Agent not found | The agent id is unknown, or the agent belongs to another workspace. | Use an id from GET /v1/agents with a key of the agent's workspace. | | 409 | Cannot start a session on an archived agent | The agent is archived. | Restore it with POST /v1/agents/{agentId}/restore, then start the session. | | 409 | This agent has reached its call limit. Try again later. | A voice start found the agent already has as many calls open as it allows, the workspace's plan already has as many calls open at once as it allows, or the agent has had as many calls today as it allows. | Try again later. | | 409 | This agent has reached its chat limit. Try again later. | The agent already has as many chats open as it allows, the workspace's plan already has as many chats open at once as it allows, or the agent has had as many chats today as it allows. | Try again later. | | 413 | Request body is larger than 100 KB | The JSON body is over 100 KB; the request is rejected before the API key is checked, so it has no Activity row. | Send a smaller body; long text belongs in several calls. | | 415 | Content-Type must be application/json | The request has a body whose Content-Type is not application/json. | Send Content-Type: application/json. | | 429 | ThrottlerException: Too Many Requests | The key made more than 10 requests to this endpoint in 60 seconds; a Retry-After header carries the seconds to wait. | Wait Retry-After seconds, then retry. | | 500 | Something went wrong | An error the API did not classify. | Check the request, then retry after a short wait; contact support if it persists. | | 503 | Live sessions are not available right now. Try again later. | The agent runtime did not accept the session; no session is left open. | Try again later. | | 503 | Database unavailable | A transient outage inside the API. | Retry after a short wait. | | 504 | Database timed out | A transient timeout inside the API. | Retry after a short wait. | ## Code samples :::tabs ```bash title="cURL" curl -X POST "https://api.echonova.ai/v1/agents/{agentId}/sessions" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"channel":"voice"}' ``` ```python import requests response = requests.post( "https://api.echonova.ai/v1/agents/{agentId}/sessions", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={"channel":"voice"}, ) print(response.json()) ``` ```javascript const response = await fetch('https://api.echonova.ai/v1/agents/{agentId}/sessions', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ channel: 'voice' }), }); console.log(await response.json()); ``` :::