Skip to main content
This reference is generated from the protocol specification and AsyncAPI definition. The full frame-by-frame reference (every event, every close code, byte-exact golden frames) is being finalized — the sections below cover what you need to connect and exchange audio today.

​
Connect

Omni is zero-state — there is nothing to create first. You open a WebSocket, the session is authorized by your key’s organization, and you describe the behavior (voice, persona, knowledge endpoint) in the first configure frame: 
wss://api.pyai.com/v1/omni?format=pcm16&rate=24000
Authenticate on the upgrade by passing your key as a subprotocol (browser-safe): 
Sec-WebSocket-Protocol: pyai-key.pyai_live_...
Server-side clients may instead append ?api_key=... to the URL.

​
Labeling a session (optional)

You can add an optional session_label to the connect URL: 
wss://api.pyai.com/v1/omni?session_label=support-line&format=pcm16&rate=24000
session_label is an opaque tag — PyAI stores no per-session state; the value is simply echoed back to your own knowledge endpoint so you can correlate or branch per session. Use any value, or omit it entirely.
agent_id is a deprecated alias for session_label (and agent on the older, also-deprecated wss://api.pyai.com/v2/omni/chat URL). They still work, but new integrations should use /v1/omni with session_label.This label is not the Agents feature — the no-code create/manage/track product — and connecting an Omni session does not require creating anything. It’s just a string you tag the session with.

​
Audio format

Pass the audio format and sample rate as query parameters, e.g. ?format=pcm16&rate=24000 (browser/WebRTC) or ?format=pcm16&rate=16000 (telephony). Send audio frames as binary messages; receive the model’s speech the same way.

​
Session lifecycle (events)

On connect you receive a greeting frame followed by a session_started event. During the session you’ll see events for barge-in, DTMF passthrough, transfer, and session end. The complete event catalog with payloads and golden frames is published in the full reference below.

Full protocol reference & golden frames

Coming soon — every event payload, every close code with retry guidance, and byte-exact captures. Until then, use the official SDKs’ realtime helpers, which build the URL and subprotocol for you.

​
Close codes

The server uses standard WebSocket close codes plus PyAI-specific codes for auth, rate, and concurrency conditions. Treat 4xx-class application closes as non-retryable (fix the request) and transient/1011-class closes as retryable with backoff. The full table ships with the reference above.

​
See also