Events

CallEvent is how the gateway tells you what happened to a call after you hand the call off. The gateway pushes events on the same uni-stream pipe as audio.

`CallEvent` schema

Field	Type	When populated
`call_sid`	`string`	Always.
`event_type`	`EventType`	Always (see table below).
`status`	`string`	A coarse string for human reading: `INITIATED`, `RINGING`, `ANSWERED`, `COMPLETED`, `FAILED`, `BUSY`, `NO_ANSWER`.
`start_timestamp_ms`	`int64`	`CHANNEL_CREATE` and later events.
`q850_cause`	`int32`	`CHANNEL_HANGUP_COMPLETE`. ITU-T Q.850 cause.
`recording_url`	`string`	`CHANNEL_HANGUP_COMPLETE` if recording on.
`duration_seconds`	`int32`	`CHANNEL_HANGUP_COMPLETE`.
`answer_timestamp_ms`	`int64`	`CHANNEL_ANSWER` and later.
`end_timestamp_ms`	`int64`	`CHANNEL_HANGUP_COMPLETE`.
`packets_sent`	`uint32`	`CHANNEL_HANGUP_COMPLETE`.
`packets_received`	`uint32`	`CHANNEL_HANGUP_COMPLETE`.
`packets_lost`	`uint32`	`CHANNEL_HANGUP_COMPLETE`.
`bytes_sent`	`uint64`	`CHANNEL_HANGUP_COMPLETE`.
`jitter_ms`	`double`	`CHANNEL_HANGUP_COMPLETE`.
`estimated_mos`	`double`	`CHANNEL_HANGUP_COMPLETE`. R-factor → MOS estimate.
`trunk_id`	`string`	Always.
`tenant_id`	`string`	Always.
`codec`	`string`	Negotiated egress codec.
`timestamp_ms`	`int64`	When the gateway emitted this event.
`client_id`	`string`	An echo of `EventStreamRequest.client_id`.

Event types

`event_type` value	Name	Fired
`0` `UNKNOWN`	reserved	This value must never appear. If it appears, log the event and drop it.
`1` `CHANNEL_CREATE`	The gateway created the b-leg (callee). Do not assume audio yet.
`2` `CHANNEL_ANSWER`	The far end answered. Audio now flows.
`3` `CHANNEL_HANGUP_COMPLETE`	The final accounting event. It includes the Q.850 cause and stats.
`4` `CHANNEL_HOLD`	The caller pressed hold (or `ExecuteDialplan(MUSIC_ON_HOLD)`).
`5` `CHANNEL_RESUME`	The hold ended.

Subscribing

Send one EventStreamRequest immediately after connect. The SDKs do this for you in connect() / connect_async(). The client_id should be a stable per-process UUID. The gateway uses it to demux events when the same tenant has multiple connected SDK instances.

[u32 length][u32 method_id=959835745][envelope: client_id="..."]

After this RPC, the gateway opens server-initiated uni-streams to your session. These streams contain audio and event frames.

Ordering

For a single call_sid, the gateway emits events strictly in this order:

CHANNEL_CREATE  →  (CHANNEL_ANSWER  →  CHANNEL_HOLD ⇄ CHANNEL_RESUME …)?  →  CHANNEL_HANGUP_COMPLETE

Across call_sids, events are not ordered. The gateway pushes them as fast as it can serialize them.

Reconnect behaviour

Within a session: If a uni-stream resets mid-frame, the gateway opens a new one. It replays the latest CHANNEL_HANGUP_COMPLETE for each call that completed during the gap. The gateway does not replay mid-call events, because you already missed the audio.
Across sessions: A fresh QUIC connection with the same client_id resumes the subscription. The gateway holds an event buffer of 120 seconds per client_id. It drops anything older.

Recommended consumer pattern

Track in-flight call_sids in a set. Remove them on CHANNEL_HANGUP_COMPLETE. Do not drive UI from status strings alone. Those strings are for humans. Branch on event_type. Use q850_cause to disambiguate hang-up reasons.

ACTIVE: set[str] = set()

def on_event(ev):
    if ev.event_type == EventType.CHANNEL_CREATE:
        ACTIVE.add(ev.call_sid)
    elif ev.event_type == EventType.CHANNEL_HANGUP_COMPLETE:
        ACTIVE.discard(ev.call_sid)
        if ev.q850_cause in (17, 18, 19):  # busy / no_user_response / no_answer
            schedule_retry(ev.call_sid)

Getting Started

Concepts

Raw RPC Format

Telephony Reference

Platform

Admin API (raw RPC, no SDK)

`CallEvent` schema

Event types

Subscribing

Ordering

Reconnect behaviour

Recommended consumer pattern

​CallEvent schema

​Event types

​Subscribing

​Ordering

​Reconnect behaviour

​Recommended consumer pattern

`CallEvent` schema

Event types

Subscribing

Ordering

Reconnect behaviour

Recommended consumer pattern