Guides

Telephony & Phone Numbers

How Threll workers connect to the phone network: the two transport types, how numbers are bound to workers, Quick Connect for inbound forwarding, and what every telephony error means.

The model: numbers belong to workers

Telephony is configured per worker, not per account. Each worker can hold:

outboundPhoneNumberstring

The caller ID used when this worker places calls. A worker without one cannot make outbound calls.

inboundPhoneNumberstring

The number this worker answers on. Customers dialing it reach this worker directly.

When you start a call, you choose the worker — and therefore the from-number. Both fields are visible on the Worker resource.

Transport types

Every phone call rides on one of two transports. Threll picks automatically per call based on the integration assigned to the worker:

Transport	When it's used
`twilio`	WebSocket media via Twilio. Used when the account has a Twilio integration and no SIP integration is assigned to the worker.
`sip_trunk`	SIP trunking. Used automatically whenever a SIP trunk integration is assigned to the worker. Takes precedence over Twilio.

There is no transport parameter on the API — assignment of integrations to workers determines the route. If a call resolves to a transport that can't carry it, the API returns a TELEPHONY_TRANSPORT_NOT_SUPPORTED error.

Twilio (WebSocket)

The standard route. Threll streams call audio over a WebSocket to Twilio. Set up the Twilio integration on your account in the platform, then assign it to each worker that should place or receive calls. Two distinct errors tell you which step is missing:

TELEPHONY_INTEGRATION_NOT_SETUP — the account has no telephony integration at all.
TELEPHONY_INTEGRATION_NOT_ADDED_TO_WORKER — the account is set up, but this specific worker isn't assigned to it.

SIP trunking

For bringing your own carrier or PBX, Threll connects over a SIP trunk. We currently support two SIP trunk providers out of the box:

Telenor — set up self-service in the platform under Settings → Integrations → Telenor SIP.
Twilio SIP trunk — set up self-service in the platform under Settings → Integrations → Twilio SIP. Distinct from the regular Twilio WebSocket integration above.

Threll also supports other SIP trunks (3CX, Sinch, Telia, custom carriers, on-prem PBX, etc.) — but these require manual provisioning. Contact us with your trunk's connection details (account SID, API key, API base URL, application SID, and trunk group if applicable) and we'll get the integration set up on your account.

Once a SIP integration is assigned to a worker, all of that worker's calls route over the trunk automatically.

Quick Connect: forward your existing number

You usually don't want to print a new phone number on your website. Quick Connect lets a worker answer your existing business number by call forwarding, with a verification step to prove you control the number:

Start verification

In the platform, enter the business number you want to forward. Threll generates a 6-digit verification code and a forwarding target number. The code is valid for 10 minutes.

Enable forwarding

Activate call forwarding from your business number to the forwarding target (with your carrier or PBX, e.g. *21* codes on most Nordic carriers).

Verify

Threll matches the forwarded call to your pending session by the forwarded-from number and confirms the code. On success, the worker's inboundPhoneNumber is set to your business number and the worker starts answering its calls.

If the code expires before you complete the steps, start over — expired sessions are simply discarded, nothing is changed on the worker.

Checking telephony status programmatically

Before placing calls from an integration, verify the worker can actually dial:

REST — fetch the worker and check outboundPhoneNumber is present.
MCP — call the get_telephony_status tool, which reports per worker: outbound number, inbound number, and telephony provider.

Telephony error reference

All telephony errors are 400 responses with a structured body (see Errors):

Error type	Meaning	Fix
`TELEPHONY_INTEGRATION_NOT_SETUP`	No telephony integration on the account.	Set up Twilio or SIP in the platform.
`TELEPHONY_INTEGRATION_NOT_ADDED_TO_WORKER`	The worker isn't assigned to the integration.	Assign the integration to the worker.
`TELEPHONY_TRANSPORT_NOT_SUPPORTED`	The call resolved to a transport that can't carry it.	Check the worker's integration assignment.
`TELEPHONY_THRELL_PROVIDER_UNAVAILABLE`	The Threll voice provider failed to start the session. The call is marked failed.	Transient — retry later.
`CALL_SCRIPT_NOT_CONFIGURED`	The worker has no call script for outbound calls.	Configure a call script, or pass one explicitly.

Next steps

Working with the REST API

Start your first outbound call.

Read guide →

Scheduled Calls

Queue calls for later and understand dispatch timing.

Read guide →

Next: Scheduled Calls