Skip to main content
Phone numbers connect your Twilio numbers to TurnCall agents. Each number can route to a specific agent or to a webhook for dynamic routing.

​
Bind a Phone Number

​
Static routing (to an agent)

​
Dynamic routing (server URL)

Route calls to a webhook that decides which agent to use:
See Call Init for details on how dynamic routing works.

​
Bring your own Twilio account

A number can run on its own Twilio account instead of the platform’s TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN. Send the pair — both or neither — and external_number_sid becomes optional: TurnCall looks the number up on that account, which is also what proves the account owns it.
  • Credentials that Twilio rejects, or that do not own the number, are a 422 — nothing is bound.
  • The token is stored encrypted under CREDENTIAL_ENCRYPTION_KEY and never returned. Reads carry twilio_account_sid and twilio_credentials (number or platform).
  • Every Twilio operation for that number uses its account: webhook configuration, outbound calls, hang-up, transfer, DTMF, recording download, and the signature check on its inbound webhooks (matched by the webhook’s AccountSid).
  • PUT /v1/phone-numbers/{id} with a new pair replaces it — rotating a token. Omitting the pair keeps the stored one.
With no platform Twilio account configured, an inbound webhook TurnCall cannot verify passes only while no number carries its own account (a development setup). Once any does, an unverifiable webhook is refused.
Binding with a server_url returns a server_url_secret — TurnCall signs each call-init request with it so your endpoint can verify the source.

​
Update a Binding

Re-route a number in place — the phone id and its server_url_secret stay stable, so a call-init endpoint keeps verifying with the same secret across edits:
A secret is minted only when server_url appears on a number that never had one; it is never rotated implicitly.

​
Configure Twilio

TurnCall sets these on bind when PUBLIC_BASE_URL is configured (the response says so in twilio_webhooks_configured). To set them by hand:
  • Voice URL: https://your-host/webhooks/twilio/voice/inbound (POST)
  • Status URL: https://your-host/webhooks/twilio/status (POST)

​
SMS Support

Enable SMS on a phone number to handle both voice calls and text messages:
When sms_enabled: true is set on bind, TurnCall auto-configures the Twilio SMS webhook. See SMS / Chat for details.

​
WhatsApp Support

Enable WhatsApp on a phone number:
See WhatsApp for full setup instructions.