Call routing

How a call gets from the PSTN to your application — and how you decide what happens next.

Inbound calls

1. A caller dials one of your numbers.
2. The call enters through a SIP gateway, which authenticates the source IP against your trunk's inbound allowlist.
3. The switch answers and looks up the number's configuration:
   • Voice URL — the switch fetches TwiML from your server and executes it.
   • Ring group — the switch rings every online, registered agent in the group; the first to answer claims the call.
4. Status events fire to your statusCallback URL as the call progresses.

Outbound calls

1. You POST to /Calls with a destination and TwiML (inline or via URL).
2. The call is queued at your account's Calls Per Second (CPS) rate.
3. The switch dials the destination through the account's assigned SIP trunk (or the client gateway for agent extensions).
4. On answer, the switch fetches and executes the TwiML.

TwiML execution

Each verb runs in order:

• <Say> / <Play> — speak or play audio.
• <Gather> — wait for input, then request the action URL.
• <Record> — capture audio, then request action.
• <Dial> — bridge to a number, SIP, client, or conference. When the leg ends, execution continues after <Dial> (or the action URL is requested).
• <Redirect> — fetch a new TwiML document.

Ring groups

A ring group routes an inbound call to every available agent simultaneously. Availability is the intersection of:

• agent status online (set via the dashboard or agent extensions API), and
• a live SIP registration (the browser device is registered).

First answer wins; the remaining agents are released. Ring-group calls still report status via webhooks and can be recorded like any call.

Conferences

Use <Dial><Conference> to bring multiple parties into a shared bridge. Conferences can be recorded (record on the <Dial>) and are a common building block for support queues and warm transfers.

Troubleshooting a failed route

Symptom	Cause	Fix
403 / rejected INVITE	Source IP not in trunk allowlist	Add the IP to the trunk's inbound_source_ips.
503 on lookup	Switch / dispatcher unreachable	Check dispatcher list and switch health.
Ring group rings, nobody answers	Agents not online / registered	Set status online and keep the device registered.
One-way audio	NAT / RTP reachability	Ensure media can reach the endpoint; check RTPEngine / published ports.

See SIP trunks and WebRTC softphone for deeper guidance.