Skip to main content

Phone Numbers

Phone numbers are the entry point for calls into VOCALS. Each number is connected to a Twilio SIP trunk and assigned to an agent that handles all calls to that number.

Adding a Twilio Phone Number​

Prerequisites​

  • A Twilio account with at least one purchased phone number.
  • Your Twilio Account SID and Auth Token (available in the Twilio Console under Account > API keys & tokens).

Steps​

  1. Navigate to Phone Numbers in the VOCALS dashboard.
  2. Click Add Number.
  3. Enter your Twilio Account SID and Auth Token if you have not already connected your Twilio account.
  4. VOCALS will fetch your available Twilio phone numbers. Select the number you want to use.
  5. Assign an agent to the number.
  6. Click Save.

VOCALS automatically configures the Twilio webhook URLs on the number so incoming calls are routed to your VOCALS orchestrator.

SIP Trunk Configuration​

VOCALS receives calls via Twilio SIP trunks. When you add a phone number, VOCALS configures a SIP trunk that routes calls to the VOCALS platform.

How It Works​

Caller dials number
    |
Twilio PSTN receives call
    |
Twilio routes to SIP trunk
    |
SIP trunk connects to VOCALS orchestrator
    |
VOCALS opens a WebSocket Media Stream
    |
Real-time audio streaming begins (mulaw/8kHz)

Manual SIP Configuration​

If you need to configure the SIP trunk manually (e.g., for custom networking or firewall rules):

  1. In the Twilio Console, go to Elastic SIP Trunking > Trunks.
  2. Create a new trunk or select an existing one.
  3. Under Origination, add a URI pointing to your VOCALS server: 
    sip:your-vocals-domain.com:5060
  4. Under Termination, configure the termination SIP URI if you need outbound calling.
  5. Under Phone Numbers, associate your Twilio number with this trunk.
info

For most users, VOCALS handles SIP trunk configuration automatically. Manual configuration is only needed for advanced networking setups or when running VOCALS behind a custom firewall.

Assigning Numbers to Agents​

Each phone number maps to exactly one agent. When a call arrives on that number, VOCALS loads the assigned agent's configuration (system prompt, providers, settings) and starts the voice pipeline.

To Change the Agent Assignment​

  1. Go to Phone Numbers in the dashboard.
  2. Click the number you want to update.
  3. Select a different agent from the dropdown.
  4. Click Save.

The change takes effect on the next incoming call. Active calls are not affected.

Multiple Numbers, One Agent​

You can assign the same agent to multiple phone numbers. This is useful when:

  • You have local numbers in different area codes that all route to the same agent.
  • You want separate numbers for tracking purposes (e.g., one number per marketing campaign) but the same conversational experience.

One Number, Different Behaviors​

If you need different behavior based on time of day or caller attributes, create separate agents and use VOCALS API to programmatically switch the agent assignment. For example, assign a "Business Hours" agent during the day and an "After Hours" agent at night.

Number Management​

Status Indicators​

StatusMeaning
ActiveNumber is configured and receiving calls.
InactiveNumber is added but not assigned to an agent. Calls to this number will not be answered.
ErrorTwilio webhook configuration failed. Check your Twilio credentials.

Removing a Number​

  1. Go to Phone Numbers and select the number.
  2. Click Remove.
  3. Confirm the removal.

This only removes the number from VOCALS. The number remains in your Twilio account and can be re-added later. VOCALS will reset the Twilio webhook configuration on the number so it no longer routes to your orchestrator.