Create session
Create a voice Session: a short-lived, single-conversation reservation that lets a client hold a live voice chat with your agent. This is step 1 of 2. Creating the Session does not start any audio on its own; it returns a ws_url that a client then connects to over WebSocket to actually talk.
Connect the client and talk
The ws_url alone does nothing until a client connects to it. Creating the session is step 1;
connecting a client is step 2. Your API key stays on your server: the client only ever receives
the ws_url, which is single use and expires.
- The token is valid to connect for 15 minutes after creation.
- It covers one conversation and dies when that conversation ends.
- Connect to the
ws_urlexactly as returned. Never build, edit, or cache it; the format is not part of the contract. - If the connection drops mid-call, reconnecting to the same
ws_urlre-attaches to the same conversation, so a brief network blip does not lose the call.
Two client paths, both using the same ws_url:
- Browser: the
@omnidim-ai/clientweb SDK handles microphone capture, agent audio playback, barge-in, and transcripts. - Any other platform: speak the wire protocol in Web call protocol: 16 kHz mono PCM16 frames in, audio and transcript events out.
Reseller keys only: the id of one of your direct client users. The call then acts as that client, on that client's agents, numbers, campaigns and balance. Calls, sessions and bulk campaigns spend that client's balance and concurrency. Omit it to act on your own account. Send it as a JSON integer in the body. null, 0, false or your own user id also means your own account. Any other value that is not a positive integer id is refused with 400 invalid_request. A key that is not a reseller's gets 403 when it names someone else. A user who is not your direct client gets 404.
ID of the agent the session talks to.
The session type. Only voice is supported.
Per-session variables that personalize the conversation. Set server-side, so visitors cannot tamper with them. Two reserved keys are read as instructions for this session and never reach the agent: __languages and __post_call_actions.
curl -X POST 'https://backend.omnidim.io/api/v1/sessions/create' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "user_id": 1234, "agent_id": 158910, "type": "voice", "custom_variables": { "name": "Demo User" }, "metadata": { "crm_lead_id": "lead_9876", "source": "website_form" } }'
{ "session_id": 4521, "token": "sess_51gF2qw8LxNz0vY4mT7Ka3RjD9pBcE6HuWiQnZsX0oM", "expires_at": "2026-07-17T12:15:00Z", "ws_url": "wss://live.omnidim.io/chat/start_voice_chat?request_token=sess_51gF2qw8LxNz0vY4mT7Ka3RjD9pBcE6HuWiQnZsX0oM", "post_call_actions_applied": [ "email", "webhook" ], "post_call_actions_ignored": [ { "channel": "webhook", "code": "invalid_url", "message": "Webhook URL must point to an address reachable from the internet. Local and private network addresses cannot receive your call data. If you are testing locally, use a tunnel URL instead." } ] }
BearerAuthAuthorizationBearer <token>Bearer token authentication. Obtain your API key from the OmniDimension dashboard.
application/jsonuser_id?ClientUserIdReseller keys only: the id of one of your direct client users. The
call then acts as that client, on that client's agents, numbers,
campaigns and balance. Calls, sessions and bulk campaigns spend that
client's balance and concurrency. Omit it to act on your own account.
Send it as a JSON integer in the body. null, 0, false or your
own user id also means your own account. Any other value that is not
a positive integer id is refused with 400 invalid_request. A key
that is not a reseller's gets 403 when it names someone else. A
user who is not your direct client gets 404.
agent_id*integerID of the agent the session talks to.
type*"voice"The session type. Only voice is supported.
"voice""voice"custom_variables?Per-session variables that personalize the conversation.
Set server-side, so visitors cannot tamper with them.
Two reserved keys are read as instructions for this session
and never reach the agent: __languages and
__post_call_actions.
metadata?Key-value pairs stored on the session for your own
tracking (e.g. CRM or lead IDs). Not shared with the
agent; echoed back as metadata in the post-call
webhook so you can correlate results with your records.
Response body
application/jsonSession created.
application/jsonsession_id?integerCorrelate this with call logs and support requests.
token?stringThe Session Token. Single conversation, unguessable.
expires_at?stringEnd of the 15-minute connect window (UTC).
date-timews_url?stringConnect your client to this URL as returned.
post_call_actions_applied?array<string>Channels from __post_call_actions that will run for this session. Present only when __post_call_actions was sent.
post_call_actions_ignored?Items from __post_call_actions that were skipped. Present only when __post_call_actions was sent. When nothing was applied, the agent's own post-call actions run.