Skip to main content
Two ways to put an agent on a phone line:
  1. Assign a number in Omnia — import it, attach it to an agent, done. See Phone numbers.
  2. Bring your own telephony — you keep the carrier relationship and stream audio to us. That is this page.
BYOT is right when you already run a telephony stack, need call control we do not expose, or must keep numbers on an existing account.

The flow

1

A call arrives at your carrier

Your webhook is hit, as it is today.
2

You create an Omnia call session

POST /calls/create with the agent and your connectionType.
3

You bridge the audio

Point the carrier’s media stream at the returned websocketUrl.

Creating the session

enum
default:"twilio"
twilio, telnyx, plivo, websocket, or webrtc. Anything else returns 400.
Telephony transports use G.711 audio regardless of what you send in the websocket block — that is what the phone network carries. Sample rates and codec are only read when connectionType is websocket.

Twilio

Answer the call with a <Stream> pointed at the websocketUrl:
In your webhook handler:
<Connect><Stream> is bidirectional — the agent can speak back. <Start><Stream> is send-only and will give you an agent that hears the caller but cannot answer.

Telnyx and Plivo

Identical shape — set connectionType accordingly and point the provider’s media-stream feature at websocketUrl. The audio contract is the same G.711.

Your own client

For a mobile app or a custom bridge, use connectionType: "websocket" and pick your own audio parameters:
See the WebSocket protocol for the message types.

Practical notes

A websocketUrl is short-lived and single-use. Create one when the call arrives, never at boot, and never cache it.
The caller hears silence from the moment they are answered until audio starts flowing. Create the session and return your XML in one round trip — do not do database work in between.
BYOT bills the same per-minute rate. An out-of-credit workspace fails at session creation with 402, so handle that in your webhook and play your own message rather than returning broken XML.
Assign the hangUp system tool so the agent can end the call itself. Your carrier’s own hangup handling stays yours.