Sessions

A session is one conversation between a visitor and an agent.

tip

The quickest way to put an agent on your website is the widget embed code from a website channel. It calls these endpoints for you. See Website widget channel. Use the endpoints below only if you build your own client.

Start a session

POST/widget/v1/session

Starts a voice session with an agent and returns a short-lived token. Your client uses the token to open a realtime voice connection with the provider named in model.

Before the session starts, the API checks that your organization has credit and a free voice line. A session reserves some credit while it runs.

Requires the widget:session permission.

Headers

X-API-Keystringrequired

Your project API key.

Body

agent_idintegerrequired

The agent to talk to. Get IDs from GET /widget/v1/config.

modelstringoptional

Override the agent's voice provider for this session. Accepts openai or gemini. Any other value is ignored and the agent's own setting is used.

voicestringoptional

Override the agent's voice for this session.

contextobjectoptional

Details about the visitor, as key and value pairs, for example {"name": "Asha", "plan": "Gold"}. The agent sees them at the start of the conversation. Empty values are skipped.

user_idstringoptional

Your own ID for a signed-in visitor, up to 128 characters. Used by Agent Memory to recognise returning visitors. Send it with user_hash.

user_hashstringoptional

The HMAC-SHA256 signature of user_id, as hex. See Agent Memory for how to compute it on your server.

visitor_idstringoptional

An anonymous ID for this browser, up to 64 characters. Used by Agent Memory when there is no user_id.

Response fields

successbooleanoptional

true when the session started.

session_idstringoptional

The session ID. Send it with tool calls and session events.

agent_idintegeroptional

The agent ID.

agent_namestringoptional

The agent name.

modelstringoptional

The voice provider for this session: openai or gemini.

voice_llm_modelstring or nulloptional

The provider model the token was issued for.

client_secretobjectoptional

The short-lived token for the provider connection.

client_secret.ephemeral_tokenstringoptional

The token value.

client_secret.expires_atinteger or nulloptional

When the token expires, as a Unix timestamp in seconds.

ice_serversarray or nulloptional

ICE servers to use for the WebRTC connection, when the provider needs them.

initial_messagestring or nulloptional

The agent's greeting.

Responses

200

The session started.

400

The session could not be set up for this agent. detail says why.

401

The key is invalid, revoked, lacks widget:session, or is not allowed from this domain.

402

Your organization has no active subscription or not enough credit.

403

The key cannot use this agent, the agent is in another project, or your plan does not include a feature the agent uses.

404

The agent was not found.

422

A field is missing or invalid, for example agent_id is missing or user_id is longer than 128 characters.

429

The key's rate limit was reached, or all your voice lines are in use.

cURL

curl -X POST https://in.api.voisx.ai/widget/v1/session \
  -H "X-API-Key: $VOISX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 2210,
    "context": { "name": "Asha" }
  }'

Node.js

const res = await fetch("https://in.api.voisx.ai/widget/v1/session", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.VOISX_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: 2210,
    context: { name: "Asha" },
  }),
});
const session = await res.json();

Python

import os
import requests

res = requests.post(
    "https://in.api.voisx.ai/widget/v1/session",
    headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
    json={"agent_id": 2210, "context": {"name": "Asha"}},
)
session = res.json()

200 OK

{
  "success": true,
  "session_id": "6f1c2a9e-3b7d-4e2a-9c51-0d8e4f7a1b23",
  "agent_id": 2210,
  "agent_name": "Reception",
  "model": "openai",
  "voice_llm_model": "[provider model]",
  "client_secret": {
    "ephemeral_token": "[short-lived token]",
    "expires_at": 1791200000
  },
  "ice_servers": null,
  "initial_message": "Hi, how can I help?"
}

429 Too Many Requests

{
  "detail": "Concurrent call limit reached: 5 of 5 voice lines are in use. Wait for a call to end, or ask your account team for extra lines."
}

warning

The token in client_secret is short-lived and only works for this session. Request a new session for each conversation. Do not cache or reuse it.

Get an ElevenLabs signed URL

GET/widget/v1/elevenlabs-convai/signed-url

For agents that run on ElevenLabs Conversational AI. Returns a signed URL your client uses to connect to ElevenLabs directly. You can tell these agents apart in GET /widget/v1/config: their elevenlabs_convai_agent_id is set.

Your plan must include ElevenLabs voice. Requires the widget:session permission.

Headers

X-API-Keystringrequired

Your project API key.

Query parameters

agent_idintegerrequired

The agent to talk to.

Response fields

signed_urlstringoptional

The URL to open the ElevenLabs conversation with. It is short-lived.

Responses

200

The signed URL.

400

The agent is not set up for ElevenLabs Conversational AI.

401

The key is invalid, revoked, lacks widget:session, or is not allowed from this domain.

402

Your organization has no active subscription or not enough credit.

403

The key cannot use this agent, or your plan does not include ElevenLabs voice.

404

The agent was not found.

429

The key's rate limit was reached.

502

ElevenLabs returned an error. Retry after a short wait.

503

The agent service is temporarily unavailable.

cURL

curl "https://in.api.voisx.ai/widget/v1/elevenlabs-convai/signed-url?agent_id=2210" \
  -H "X-API-Key: $VOISX_API_KEY"

Node.js

const url = new URL("https://in.api.voisx.ai/widget/v1/elevenlabs-convai/signed-url");
url.searchParams.set("agent_id", "2210");

const res = await fetch(url, {
  headers: { "X-API-Key": process.env.VOISX_API_KEY },
});
const { signed_url } = await res.json();

Python

import os
import requests

res = requests.get(
    "https://in.api.voisx.ai/widget/v1/elevenlabs-convai/signed-url",
    headers={"X-API-Key": os.environ["VOISX_API_KEY"]},
    params={"agent_id": 2210},
)
signed_url = res.json()["signed_url"]

200 OK

{
  "signed_url": "[signed ElevenLabs URL]"
}