Create session

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_url exactly 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_url re-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/client web 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.

curl -X POST 'https://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."
    }
  ]
}