Types

Every type below is a serde envelope. Fields are encoded in the order listed. See Envelope Format for primitive encodings.

Enums

`ErrorCode` (encoded as `int32`)

Value	Name	Meaning
`0`	`SUCCESS`	The gateway accepted the request.
`1`	`ERR_INVALID_TRUNK`	Unknown or unauthorized `trunk_id`.
`2`	`ERR_INVALID_DESTINATION`	The gateway could not parse or route `to`.
`3`	`ERR_RATE_LIMITED`	The per-tenant CPS budget is exhausted.
`4`	`ERR_CIRCUIT_BREAKER`	The trunk is unhealthy. The gateway sheds load.
`5`	`ERR_INTERNAL_ERROR`	An unspecified gateway-side failure.
`6`	`ERR_VALIDATION_FAILED`	The DTO failed schema validation.
`7`	`ERR_UNAUTHORIZED`	The JWT is missing, expired, or for the wrong tenant.

`DialplanAction` (encoded as `int32`)

You can use values 0-6 as default_app on Originate. Values 7-12 are call-control verbs. They are valid only through ExecuteDialplan against an active call_sid.

Value	Name	Notes
`0`	`HANGUP`
`1`	`PARK`
`2`	`MUSIC_ON_HOLD`
`3`	`PLAYBACK`	`app_args` = absolute path to .wav
`4`	`UNPARK_AND_BRIDGE`	`app_args` = target call_sid
`5`	`ANSWER`
`6`	`AI_BIDIRECTIONAL_STREAM`	`app_args` = agent_id
`7`	`TRANSFER`	RFC 3515 SIP REFER. `app_args` = destination URI or E.164.
`8`	`MUTE`	`app_args` = "" (gateway-side TX silence) or `"wire"` (also recvonly re-INVITE).
`9`	`UNMUTE`	Same `app_args` shape as MUTE.
`10`	`HOLD`	A sendrecv → sendonly re-INVITE. The opposite leg gets MOH if the trunk is configured for it.
`11`	`UNHOLD`	Lifts a previous HOLD.
`12`	`SEND_DTMF`	`app_args` = `"<digit>:<mode>:<duration_ms>"` (mode = rfc2833 \| info; `inband` is not supported today).

`InboundRule` (encoded as `int32`)

Value	Name
`0`	`REJECT`
`1`	`PLAY_AND_HANGUP`
`2`	`NOTIFY_AND_HANGUP`
`3`	`HANDLE_AI`

`EventType` (encoded as `int32`)

Value	Name
`0`	`UNKNOWN`
`1`	`CHANNEL_CREATE`
`2`	`CHANNEL_ANSWER`
`3`	`CHANNEL_HANGUP_COMPLETE`
`4`	`CHANNEL_HOLD`
`5`	`CHANNEL_RESUME`

Request DTOs

`OriginateRequest`

Field	Type	Notes
`trunk_id`	`string`	The configured outbound trunk to use.
`to`	`string`	An E.164 number or a full SIP URI.
`call_from`	`string`	The caller-ID. Per-trunk allow-listing applies.
`ai_websocket_url`	`string`	If set, the gateway dials the AI bridge over WS for this call.
`ai_quic_url`	`string`	The same, but over QUIC. Set one of the two when you use `AI_BIDIRECTIONAL_STREAM`.
`tenant_id`	`string`	Echoed for audit. It must match the JWT tenant.
`max_duration_ms`	`int32`	Hard cap. `0` = trunk default.
`call_sid`	`string`	Optional client-provided idempotency key.
`default_app`	`DialplanAction`	What the call lands in once answered. The control-plane API (`telephony.originate`) defaults this to `AI_BIDIRECTIONAL_STREAM` (=6) when omitted. The polyglot SDK signatures default to `PARK` (=1) at the C-FFI boundary.
`default_app_args`	`string`	A per-app argument string (e.g. playback URL, agent_id). With `default_app=AI_BIDIRECTIONAL_STREAM` and an empty `default_app_args`, the runtime has no agent to bridge. The call answers silent.
`auto_barge_in`	`bool`	Allow late `Barge` calls without re-handshake.
`barge_in_patience_ms`	`int32`	The grace window for the bargee before forced merge.
`client_id`	`string`	The UUID of the SDK process. The gateway routes `CallEvent`s back with it.

`BulkRequest`

Field	Type	Notes
`csv_url`	`string`	The HTTPS URL of a CSV. The first column is the E.164 destination.
`template_trunk_id`	`string`	Same as `OriginateRequest.trunk_id` for every row.
`template_to`	`string`	Override the CSV’s `to` (rarely used).
`template_call_from`	`string`
`template_ai_websocket_url`	`string`
`template_ai_quic_url`	`string`
`template_tenant_id`	`string`
`template_max_duration_ms`	`int32`
`template_default_app`	`DialplanAction`
`template_default_app_args`	`string`
`calls_per_second`	`int32`	Pacing.
`max_concurrent_calls`	`int32`	The cap on simultaneous in-flight calls.
`campaign_id`	`string`	`AbortBulk` uses it.

Single-field requests

DTO	Field
`AbortBulkRequest`	`string campaign_id`
`TerminateRequest`	`string call_sid`
`BargeRequest`	`string call_sid`
`EventStreamRequest`	`string client_id`
`GetIncomingCallsRequest`	`string trunk_id`
`BucketRequest`	`string bucket_id`

`SetInboundRoutingRequest`

Field	Type
`trunk_id`	`string`
`rule`	`InboundRule`
`audio_url`	`string`
`webhook_url`	`string`
`ai_websocket_url`	`string`
`ai_quic_url`	`string`

`AnswerIncomingCallRequest`

Field	Type
`call_sid`	`string`
`ai_websocket_url`	`string`
`ai_quic_url`	`string`

`BucketActionRequest`

Field	Type	Notes
`bucket_id`	`string`
`action`	`int32`	`0=hangup`, `1=unpark+bridge`, `2=playback`

`ExecuteDialplanRequest`

Field	Type
`call_sid`	`string`
`action`	`DialplanAction`
`app_args`	`string`

Response DTOs

`OriginateResponse` / `TerminateResponse` / `AnswerIncomingCallResponse`

Field	Type
`call_sid`	`string`
`status`	`string`
`error_message`	`string`
`error_code`	`ErrorCode`
`timestamp_ms`	`int64`

`BulkResponse`

Field	Type
`status`	`string`
`loaded_numbers`	`int32`

`GetIncomingCallsResponse`

Field	Type
`calls`	`vector<IncomingCallInfo>`

`IncomingCallInfo`

Field	Type
`call_sid`	`string`
`call_from`	`string`
`start_timestamp_ms`	`int64`

`ListBucketsResponse`

Field	Type
`buckets`	`vector<BucketInfo>`

`BucketInfo`

Field	Type
`bucket_id`	`string`
`pending_count`	`int32`

`BucketCallList`

Field	Type
`call_sids`	`vector<string>`

`BucketActionResponse`

Field	Type
`processed_count`	`int32`

`ExecuteDialplanResponse`

Field	Type
`status`	`string`
`error_message`	`string`
`error_code`	`ErrorCode`

`Empty`

No fields. The serde envelope is only the 6-byte header (v=0, cv=0, payload_size=0).

Getting Started

Concepts

Raw RPC Format

Telephony Reference

Platform

Admin API (raw RPC, no SDK)

Enums

`ErrorCode` (encoded as `int32`)

`DialplanAction` (encoded as `int32`)

`InboundRule` (encoded as `int32`)

`EventType` (encoded as `int32`)

Request DTOs

`OriginateRequest`

`BulkRequest`

Single-field requests

`SetInboundRoutingRequest`

`AnswerIncomingCallRequest`

`BucketActionRequest`

`ExecuteDialplanRequest`

Response DTOs

`OriginateResponse` / `TerminateResponse` / `AnswerIncomingCallResponse`

`BulkResponse`

`GetIncomingCallsResponse`

`IncomingCallInfo`

`ListBucketsResponse`

`BucketInfo`

`BucketCallList`

`BucketActionResponse`

`ExecuteDialplanResponse`

`Empty`

Streaming DTOs

`AudioFrame` — see Audio Frames

`CallEvent` — see Events

​Enums

​ErrorCode (encoded as int32)

​DialplanAction (encoded as int32)

​InboundRule (encoded as int32)

​EventType (encoded as int32)

​Request DTOs

​OriginateRequest

​BulkRequest

​Single-field requests

​SetInboundRoutingRequest

​AnswerIncomingCallRequest

​BucketActionRequest

​ExecuteDialplanRequest

​Response DTOs

​OriginateResponse / TerminateResponse / AnswerIncomingCallResponse

​BulkResponse

​GetIncomingCallsResponse

​IncomingCallInfo

​ListBucketsResponse

​BucketInfo

​BucketCallList

​BucketActionResponse

​ExecuteDialplanResponse

​Empty

​Streaming DTOs

​AudioFrame — see Audio Frames

​CallEvent — see Events

Enums

`ErrorCode` (encoded as `int32`)

`DialplanAction` (encoded as `int32`)

`InboundRule` (encoded as `int32`)

`EventType` (encoded as `int32`)

Request DTOs

`OriginateRequest`

`BulkRequest`

Single-field requests

`SetInboundRoutingRequest`

`AnswerIncomingCallRequest`

`BucketActionRequest`

`ExecuteDialplanRequest`

Response DTOs

`OriginateResponse` / `TerminateResponse` / `AnswerIncomingCallResponse`

`BulkResponse`

`GetIncomingCallsResponse`

`IncomingCallInfo`

`ListBucketsResponse`

`BucketInfo`

`BucketCallList`

`BucketActionResponse`

`ExecuteDialplanResponse`

`Empty`

Streaming DTOs

`AudioFrame` — see Audio Frames

`CallEvent` — see Events