WebSocket protocol

The SDK is a convenience. If you are not in a browser — a mobile app, a server bridge, your own telephony stack — connect to the WebSocket yourself.

Getting a URL

curl -X POST "https://api.omnia-voice.com/api/v1/calls/create" \
  -H "X-API-Key: $OMNIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "AGENT_ID",
    "connectionType": "websocket",
    "websocket": { "inputSampleRate": 16000, "outputSampleRate": 16000, "codec": "pcm" }
  }'

The response carries websocketUrl:

{
  "id": "…",
  "websocketUrl": "wss://…",
  "status": "created",
  "connectionType": "websocket",
  "agent": { "id": "…", "name": "Front Desk" },
  "createdAt": "2026-08-22T09:14:02Z"
}

The field is websocketUrl. It is short-lived and single-use — create a fresh one per call rather than caching it. No additional authentication is needed on the socket itself; the URL is the credential, which is also why it must not be shared or logged.

Audio

Binary frames carry audio; text frames carry JSON.

`connectionType`	Codec	Use
`websocket`	`pcm` (or `g711`)	Direct integrations — set the sample rates you want
`twilio` / `telnyx` / `plivo`	`g711`	Telephony, forced regardless of what you send
`webrtc`	—	Browser transport, normally via the SDK

For pcm, send 16-bit mono at the inputSampleRate you requested.

Messages you receive

Type	Meaning
`transcript`	Speech recognised. Carries the speaker (`user` or `agent`) and whether it is final — see Transcripts
`state`	The agent started or stopped speaking
`client_tool_invocation`	The agent is calling one of your client tools
`hangup`	The call is ending
`error`	Something failed

Transcripts

A transcript message is one piece of one utterance. Here is what one short exchange looks like on the socket, in the order the frames arrive:

role   ordinal  final  field  value
agent  0        false  text   "Hi, you've reached the front desk."
agent  0        false  delta  " How"
agent  0        false  delta  " can"
agent  0        false  delta  " I help?"
agent  0        true   text   "Hi, you've reached the front desk. How can I help?"

       (the caller speaks)

agent  2        false  text   "Sure"
user   1        true   text   "I'd like to book an appointment."
agent  2        false  delta  ", let me check the calendar."
agent  2        true   text   "Sure, let me check the calendar."

Three things to take from that:

The agent streams. You get its words as it says them, then a closing message with the whole sentence.
The caller arrives as the final version. Their sentence comes as one message, already final: true, so there is nothing to assemble.
Order by ordinal. The caller’s utterance always has a lower ordinal than the reply it prompted, so sort by ordinal rather than by arrival.

Each field exists to let you handle exactly that:

string

required

user or agent. Decides which side of the conversation the text goes on.

integer

required

Which utterance this piece belongs to. All the agent’s delta pieces above share ordinal 0, so you know to join them. It is also the conversation order: the caller’s ordinal 1 belongs before the agent’s 2, whatever order the messages arrive in.

string

The utterance so far, in full. Present on the first piece and the last one. When you see it, replace whatever you have for that ordinal.

string

A few more characters for the same ordinal. When you see it, append. A message has text or delta, never both.

boolean

required

false means more pieces for this ordinal are coming, true means this is the last one. Use it to stop showing a typing indicator, or to know a caller turn is complete before you act on it.

string

default:"voice"

voice if it was spoken, text if you injected it with user_text_message. Useful if you want to style typed input differently.

Put together, a handler is a dozen lines:

const utterances = {};   // ordinal → { role, text, final }

ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.type !== "transcript") return;

  const u = utterances[msg.ordinal] ?? { role: msg.role, text: "" };

  if (msg.text != null) u.text = msg.text;           // full text: replace
  else if (msg.delta) u.text += msg.delta;           // delta: append
  u.final = msg.final;

  utterances[msg.ordinal] = u;

  // Render in conversation order, not arrival order.
  const ordered = Object.keys(utterances).sort((a, b) => a - b).map((k) => utterances[k]);
  render(ordered);
});

Messages you send

Type	Purpose
`client_tool_result`	Your answer to an invocation
`user_text_message`	Inject text as though the user spoke it

Client tool calls

An invocation arrives as:

{
  "type": "client_tool_invocation",
  "invocationId": "inv_abc123",
  "toolName": "transferCall",
  "parameters": { "department": "billing" }
}

Do the work, then reply with the same invocationId:

ws.send(JSON.stringify({
  type: "client_tool_result",
  invocationId: "inv_abc123",
  result: "Transferred to billing",
}));

The invocationId is how a result is matched to its call. Send a different one — or none — and the agent waits for an answer that never arrives, which the caller hears as the agent freezing mid-sentence.

Report failures rather than staying silent, so the agent can explain and move on:

ws.send(JSON.stringify({
  type: "client_tool_result",
  invocationId: "inv_abc123",
  error: "No billing agent is available right now",
}));

Using the SDK? registerTool handles all of this — invocation matching, results, and errors — so you never touch invocationId yourself.

Injecting a message

Push text into a live call as though the caller had spoken it. This is how a deferred tool result gets back into the conversation:

ws.send(JSON.stringify({
  type: "user_text_message",
  text: "The refund was approved — reference 4471.",
}));

Ending

Close the socket to hang up, or watch for the hangup message when the agent ends it. For the agent to be able to end a call gracefully, assign the hangUp system tool — without it, a finished agent simply waits.

Get started

Core concepts

Tools

Telephony

Apps & SDKs

Guides

Examples

Speech to text

Help

Getting a URL

Audio

Messages you receive

Transcripts

Messages you send

Client tool calls

Injecting a message

Ending

​Getting a URL

​Audio

​Messages you receive

​Transcripts

​Messages you send

​Client tool calls

​Injecting a message

​Ending

Getting a URL

Audio

Messages you receive

Transcripts

Messages you send

Client tool calls

Injecting a message

Ending