All newly purchased Twilio numbers will automatically answer incoming voice calls with a default sample recording, but this routing can be changed easily. This guide covers the following topics to help update the routing for your phone numbers. Click a topic to skip directly to this information:
- Create your app
- Configuration options
- Update phone number routing via Console
- Update phone number routing via an API request
Notice: Twilio phone numbers must be compliant with all local regulations in order to update the routing. For help determining your phone numbers' compliance status, see View the Regulatory Compliance Report for your Twilio Phone Numbers.
Create your app
Incoming communications to Twilio will need to be handled by an application that responds with TwiML - our XML-based markup language. Twilio reaches out to your application on incoming communications, and uses the TwiML response we receive as instructions that tell us how to respond to the call - reject it, answer it, play a message, etc.
Your Twilio response will vary depending on your use case and business needs. For full details on how Twilio Programmable Voice works, see Respond to Incoming Phone Calls (Twilio Docs).
Notice: For users looking to block calls, see How can I stop receiving or block incoming phone calls.
Once your app is ready, it will need to be posted online where Twilio can access it. We'll reach out on incoming communications, and then process the TwiML command instructions your app responds with. For hosting your app, we offer users an array of products to meet different requirements. Here are some of the most common options, and our recommendations:
TwiML Bins give users free hosting for static XML-based TwiML response scripts. We recommend this option for users who need a simple setup option for basic use cases like a playing an automated message, or forwarding to another phone number.
Studio Flows allow users to create an application with our no-code-required flowchart-style interface. We recommend this options for users who have no coding experience, or those who need to design a scalable hosted communications application.
Functions (Beta) give users free hosting for Node.js TwiML response applications. We recommend this option for users who need a scalable option to develop more robust use cases like applications that utilize NPM libraries, or make API requests.
Webhooks allow users to create TwiML response applications in XML format, or with one of our helper library SDKs, and use your own preferred hosting.
Once your application is posted, you'll need to update your phone number's routing via either the Console UI or an API request.
Update phone number routing via Console
- Access the Active Numbers page in Console.
- Click the desired phone number to modify.
- Scroll to the Voice & Fax section, and then modify the phone number’s routing. When finished, click Save.
Each routing option has different setup requirements. The following table contains selection details for the most common configurations:
|Accept incoming||Configure with||A Call comes in||Input or Drop-down|
|TwiML Bin||Voice Calls||Webhooks, TwiML Bins, Functions, Studio, or Proxy||TwiML||Select your previously saved TwiML Bin|
|Studio Flow||Voice Calls||Webhooks, TwiML Bins, Functions, Studio, or Proxy||Studio Flow||Select your previously saved Studio Flow|
|Functions||Voice Calls||Webhooks, TwiML Bins, Functions, Studio, or Proxy||Function||Select your previously saved Function|
|Webhook||Voice Calls||Webhooks, TwiML Bins, Functions, Studio, or Proxy||Webhook||Enter your Twilio application's URL|
Update phone number routing via an API request
A Twilio phone number's routing can also be changed by submitting an HTTP POST request to the
IncomingPhoneNumber REST API resource of the phone number you want to change. To make this request, you will need the following pieces of information:
- Phone number SID: The PN SID for the phone number you wish to update.
- Twilio voice app details: The URL for your Twilio app (webhook, TwiML Bin, Function, etc.), or your TwiML App SID
- Regulatory Requirements (as needed): The Identity (
RI...), Address (
AD...), or Bundle (
BU...) SID as needed for regulatory compliance.
- Project credentials: The Account SID and Auth Token for your Twilio project.
Here's an example cURL script:
curl -XPOST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/IncomingPhoneNumbers/PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json \ --data-urlencode "VoiceUrl=http://www.mysite.com/twilio" \ --data-urlencode "BundleSid=BUXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \ -u 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token'
This example will update the webhook on phone number
PN... to point incoming requests to
www.mysite.com/twilio, and use the ID documentation Bundle SID
BU... for local regulatory requirements. To make this script work for you, make the following updates, and then paste it into a terminal window:
- Line 1: update with your Twilio Account SID (
ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX) and the incoming phone number's SID (
- Line 2: update with your Twilio webhook app's URL.
- Line 3: update with the your regulatory documentation (as required).
- Line 4: update with your Account SID and Auth Token.
For additional help, see the following resources: