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.
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.
curl -X POST 'https://backend.omnidim.io/api/v1/sessions/create' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'Content-Type: application/json' \ -d '{ "agent_id": 158910, "custom_variables": { "name": "Demo User" } }'
{ "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" }
Authorization
BearerAuth Bearer token authentication. Obtain your API key from the OmniDimension dashboard.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
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. Pick one of the two client
paths below. Both use the same ws_url.
Your API key stays on your server. The browser (or any client) only ever
receives the ws_url, which is single-use and expires, so it is safe to
hand out.
Token and URL rules
- 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 WebSocket URLs; 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.
Option A: browser, with the web SDK (recommended)
The @omnidim-ai/client web SDK turns the ws_url into a
working conversation: microphone capture, agent audio playback, barge-in, and
transcripts are all handled for you.
npm install @omnidim-ai/clientimport { WebSession } from '@omnidim-ai/client';
// wsUrl came from POST /sessions/create on YOUR server.
const session = new WebSession();
session.on('status', (s) => console.log('status', s)); // connecting | active | { state: 'ended', reason }
session.on('transcript', (t) => console.log(t.role, t.text)); // { role: 'user' | 'agent', text, final }
session.on('error', (e) => console.error(e));
await session.start({ wsUrl }); // asks for mic permission, then talks
session.mute(true); // toggle the microphone
session.stop(); // hang upNo bundler? Load the UMD build from a script tag and use the
OmnidimensionClient global:
<script src="https://unpkg.com/@omnidim-ai/client"></script>
<script>
const session = new OmnidimensionClient.WebSession();
await session.start({ wsUrl });
</script>Full guide, events, and ended reasons: web SDK.
Option B: any platform, raw WebSocket protocol
For iOS, Android, Flutter, kiosks, or any client without the SDK, connect to
the ws_url and speak the wire protocol directly: send 16 kHz mono PCM16 audio
frames, and receive audio plus transcript events.
const ws = new WebSocket(wsUrl);
// Send microphone audio, one JSON frame per chunk:
ws.send(JSON.stringify({ type: 'audio', data: base64Pcm16 }));
// Receive agent audio, transcripts, and control events:
ws.onmessage = (e) => {
const msg = JSON.parse(e.data);
switch (msg.event) {
case 'media':
play(msg.media.payload); // base64 audio to play
break;
case 'clear':
stopPlaybackNow(); // barge-in: flush playback immediately
break;
case 'end_call':
hangUp(msg.media.payload.reason);
break;
// 'user' | 'partial_text' | 'system' | 'last_system_message' -> transcripts
}
};
// Hang up by closing the socket:
ws.close();Full frame reference, event table, and close codes: web call protocol.
Recap
- Your server calls this endpoint and gets a
ws_url. - Your server returns the
ws_urlto your client. - Your client connects to the
ws_url(SDK or raw protocol) and the conversation runs until it hangs up or the socket closes.