Trunks

A trunk is a named SIP/RTP egress (and ingress) profile. The public SDK refers to trunks by trunk_id when it dials. This page shows how to create and configure that trunk_id.

There is no SDK wrapper. Build the request as a serde envelope. Write it on a fresh QUIC bidirectional stream. See Raw RPC Format.

`AddTrunk` / `UpdateTrunk`

AddTrunk and UpdateTrunk accept the same DTO. Use Add for first-time provisioning. Use Update for in-place edits. Both replace the full record; there are no patch semantics. If you want to change only some fields, read the record with GetTrunk first.

Request DTO (`AddTrunkRequest` / `UpdateTrunkRequest`)

Field	Type	Default	Notes
`admin_token`	`string`		Admin JWT.
`trunk_id`	`string`		Stable identifier; this is what SDKs reference.
`channel_limit`	`uint32`	`50`	Max concurrent calls on the trunk.
`internal_sip_ip`	`string`		Gateway-side SIP bind.
`external_sip_ip`	`string`		Public IP advertised in SIP headers (NAT).
`internal_rtp_ip`	`string`		Gateway-side RTP bind.
`external_rtp_ip`	`string`		Public IP for RTP; usually equals `external_sip_ip`.
`gateway_ip`	`string`		Far-end peer (carrier / SBC).
`sbc_ip`	`string`		If routing through an SBC, its address.
`source_pbx_port`	`uint16`	`5060`	Local SIP source port.
`destination_sbc_port`	`uint16`	`5060`	Far-end SIP port.
`display_name`	`string`		Caller-ID `display-name` for outbound INVITEs.
`domain`	`string`		SIP `From` domain.
`proxy`	`string`		Outbound proxy URI, if any.
`require_registration`	`bool`	`false`	If `true`, the gateway registers with `sip_username`/`sip_password`.
`sip_username`	`string`		Registrar credentials.
`sip_password`	`string`		Registrar credentials.
`register_expires_sec`	`uint32`	`3600`	REGISTER `Expires` value.
`codec_preferences`	`vector<string>`	`[PCMU, PCMA, OPUS]`	Offer order in SDP.
`rtp_start_port`	`uint16`	`16384`	RTP port range start.
`rtp_end_port`	`uint16`	`32768`	RTP port range end.
`media_ip_cidrs`	`vector<string>`	`[]`	Allow-listed media peers. The gateway rejects SDPs that do not match.
`reject_incoming_calls`	`bool`	`true`	Inbound is default-deny. Set to `false` when you wire `inbound_rule`.
`reject_sip_code`	`uint16`	`603`	SIP response code used when rejecting.
`reject_audio_file`	`string`		URL of audio to play before rejecting (if `200 OK`-then-hangup mode).
`ignore_early_media`	`bool`	`false`	Suppress 183 Session Progress audio.
`terminate_on_hold`	`bool`	`false`	Hang up the call instead of going on hold.
`inbound_rule`	`int32`	`0`	One of `InboundRule` (0=REJECT, 1=PLAY_AND_HANGUP, 2=NOTIFY_AND_HANGUP, 3=HANDLE_AI).
`inbound_audio_url`	`string`		Used by `PLAY_AND_HANGUP`.
`inbound_webhook_url`	`string`		Used by `NOTIFY_AND_HANGUP`.
`inbound_ai_websocket_url`	`string`		Used by `HANDLE_AI`.
`inbound_ai_quic_url`	`string`		Used by `HANDLE_AI` for QUIC-side AI bridges.
`api_bearer_token`	`string`		Per-trunk webhook signing token.
`ai_websocket_url`	`string`		Default AI endpoint for outbound calls on this trunk.
`ai_quic_url`	`string`		Same, QUIC variant.
`auto_bargein_mode`	`string`	`"energy"`	`"energy"`, `"vad"`, `"semantic"`, or `"off"`.
`auto_bargein_aggressiveness`	`int32`	`2`	`0`–`3`. Higher = barge sooner.
`agent_id`	`string`		Optional bound agent DAG id (resolved server-side).

Returns Empty on success.

`RemoveTrunk`

Field	Type
`admin_token`	`string`
`trunk_id`	`string`

Returns Empty. Existing in-flight calls continue until they end normally. New originations against a removed trunk_id fail with ERR_INVALID_TRUNK.

`GetTrunk`

Request:

Field	Type
`admin_token`	`string`
`trunk_id`	`string`

Response (GetTrunkResponse):

Field	Type	Notes
`found`	`bool`	`false` ⇒ no trunk by that id.
`config`	`ApiTrunkConfig`	Sanitised view (no SIP credentials).

ApiTrunkConfig:

Field	Type	Notes
`trunk_id`	`string`
`channel_limit`	`uint32`
`display_name`	`string`
`domain`	`string`
`is_cb_tripped`	`bool`	Circuit-breaker state.
`current_asr`	`double`	Live answer-seizure ratio %.
`current_acd`	`uint32`	Live average call duration (seconds).
`current_mos`	`double`	Live mean opinion score estimate.

The gateway never returns the credential-bearing fields (sip_password, api_bearer_token, …). To rotate them, call UpdateTrunk again with the new values.

Getting Started

Concepts

Raw RPC Format

Telephony Reference

Platform

Admin API (raw RPC, no SDK)

`AddTrunk` / `UpdateTrunk`

Request DTO (`AddTrunkRequest` / `UpdateTrunkRequest`)

`RemoveTrunk`

`GetTrunk`

​AddTrunk / UpdateTrunk

​Request DTO (AddTrunkRequest / UpdateTrunkRequest)

​RemoveTrunk

​GetTrunk

`AddTrunk` / `UpdateTrunk`

Request DTO (`AddTrunkRequest` / `UpdateTrunkRequest`)

`RemoveTrunk`

`GetTrunk`