Call routing

Every setting that decides which agent and version handles a call on a number, where busy calls go, and how transfers leave the call at the SIP level.

This page brings together the routing decisions Tried makes on a phone number, in the order it makes them. Each step links to the page that covers the setting in depth.

Inbound routing order#

Step	Setting	Effect
1	Number match	The dialled number (SIP `To` user, `+` optional) must be a number in a workspace.
2	`allowed_inbound_country_list`	Callers from other countries are hung up.
3	`inbound_agents`	Weighted pick of agent and optional version. See A/B testing.
4	`inbound_webhook_url`	Your server may override the agent, version, variables and metadata, or reject the call. See Inbound call webhook.
5	Version binding	`inbound_version_ref` applies when no version was chosen yet. See Environments.
6	Pre-call workflow	The agent's pre-call workflow adds variables.
7	Concurrency	Free slot: the agent joins. No slot: hold for up to 40 seconds, then `fallback_number`, then hang up. See Inbound calls.

Outbound routing order#

Step	Setting	Effect
1	`from_number`	Must be a number in the workspace. It is the caller ID.
2	`allowed_outbound_country_list`	Destinations in other countries return 400.
3	`override_agent_id` or `outbound_agents`	The agent; a weighted pick when there are several.
4	Version	`override_agent_version`. When the request has none, `outbound_version_ref` fills it in if the request names `override_agent_id` or the number has exactly one outbound agent. Otherwise the picked entry's `agent_version`, else the latest version.
5	Concurrency	Leaves reserved inbound slots free; 429 when full. See Concurrency.
6	Calls per second	Per-number token bucket; waits up to 5 seconds, then 429.
7	Dial	LiveKit SIP dials on the number's outbound trunk with `custom_sip_headers` and the agent's `ring_duration_ms`.

Number settings reference#

All of these are on PATCH /update-phone-number/:n. Fields that change SIP configuration re-provision the number's trunks.

Field	Dashboard	Re-provisions
`nickname`	Pencil icon next to the number	no
`inbound_agents`, `outbound_agents`	Inbound Call Agent, Outbound Call Agent	no
`inbound_webhook_url`	Add an inbound webhook	no
`allowed_inbound_country_list`, `allowed_outbound_country_list`	Allowed Inbound Countries, Allowed Outbound Countries	no
`fallback_number`	Fallback number under Routing and SIP	no
`cps_limit`	Calls per second under Routing and SIP	no
`transport`, `media_encryption`	Transport, Media encryption under Routing and SIP (SIP trunk numbers)	yes
`termination_uri`, `sip_trunk_auth_username`, `sip_trunk_auth_password`	Import dialog	yes
`allowed_inbound_addresses`	API only	yes
`sip_trunk_id`	API only	yes, tears down the old trunks first

Version binding is stored separately with PUT /phone-number-bindings/:n (Agent version card).

Send null for allowed_inbound_country_list or allowed_outbound_country_list to allow every country again, and null for fallback_number or cps_limit to clear them.

Disable a direction#

Set Inbound Call Agent to None (disable inbound) (inbound_agents: []). Inbound calls are hung up unless the inbound webhook supplies an agent.
Set Outbound Call Agent to None (disable outbound) (outbound_agents: []). Outbound calls then need override_agent_id.

Transfers at the SIP level#

When an agent transfers a call, the call leaves the agent in one of these ways:

Transfer	What happens on the SIP side
Cold transfer, `sip_invite` (default)	The agent dials the destination into the same room with a new INVITE. The caller hears ringback, both legs are bridged, and the agent leaves. The caller ID can be the caller's number (`show_transferee_as_caller`).
Cold transfer, `sip_refer`	A SIP REFER asks the carrier to redirect the call. The carrier must allow REFER.
Warm transfer	The caller hears hold music, the destination is dialled, a handoff message is whispered to the person who answers, then the legs are bridged and the agent leaves.
Agentic warm transfer	A second agent talks to the person receiving the transfer, then bridges or cancels.

Transfers emit transfer_started, transfer_bridged, transfer_cancelled and transfer_ended, appear in the transcript with role transfer. The per-minute charge stops when the agent leaves; the transferred leg runs on your own trunk and your carrier bills it.

See what was sent to the carrier#

GET /telephony/operations lists the requests Tried sent to LiveKit SIP, Telnyx and Twilio for your workspace (or recorded in mock mode), newest first. Filter with provider and limit (up to 500). Use it to debug provisioning.