Troubleshooting Voice Calls

Debugging Tools

Twilio offers several tools for investigating the interaction between Twilio and your application. If a call fails to go through, or your voice call behaves unexpectedly, the Debugger and Request Inspector should be your first stops for debugging.

Debugger

Found in your Twilio console, the Debugger contains a detailed log of activity within your application. This log can help you dive deeper and understand which Twilio resources were impacted (and by whom). 

To get to the debugger, open the console navigation, then find and click on 'Runtime':

Console navigation: runtime

 Next, navigate to the Debugger:

Twilio Debugger in Runtime

Once in the debugger, you can dig into detailed logs, such as this one exposed via Events, to understand the root cause of your problem.

Twilio Debugger

Alert Triggers

You can set your own Alert triggers via the console. These will notify you via webhook or email when an error occurs on your account. 

Request Inspector

The Request Inspector provides you with information regarding the requests Twilio makes to your application as well as the responses Twilio receives. Twilio keeps these logs for 90 days.

  • Log into your Twilio account
  • Access your call logs by navigating to the Programmable Voice dashboard

          Console navigation: programmable voice

  • Then, click on the link for your Voice logs: 

          Find your Twilio Call logs

  • Once you’re in your voice logs, find the call where the problem occurred. Click the hyperlinked date to dig down into the details for this call.

          Select the Voice log for a given day

Now we can inspect the request!

The request inspector shows all requests and responses made during this call. You can easily see errors on requests by the color-coded status on the right of a request. 

Call logs: request inspector 404

Click on `Request` to expand the information.

Call log: request inspector 404b

In the above screenshot, Twilio made a request to `/action.xml` but it received a 404 back from the web server. Since Twilio didn’t receive any new TwiML to execute, the call terminated. This shows us that the web application server is sending a 404 back to Twilio, and the next step is debugging the web application itself. 

Error Codes

All Twilio-generated error codes are documented here. Find your error code and dig into causes and possible solutions.

Some Common Issues

"An application error has occurred" on your call

An 'application error' means that the code Twilio is trying to fetch at the URL specified on your servers is either unavailable or has errors in it. You can check the URL for a given phone number via your console or within your application's instructions for handling a call.

Voice Webhook

If you see this error, check your Twilio account's debugger logs for more details.

Note: Your server must be publicly accessible for Twilio to reach it. If you're building and testing locally, we recommend you use ngrok for testing your webhooks. You can follow this guide to learn how to use ngrok with Twilio.

How to Stop Receiving Calls

If you do not want to receive any phone calls with your Twilio phone number, you must remove the Voice Request URL from your Twilio phone number and leave that field blank. Without a Voice Request URL, this phone number is considered 'out of service' for inbound calls. You will not be charged for any incoming calls, nor will these calls be received and logged in your account.

To reject phone calls coming from specific phone numbers, use the <Reject> verb. As long as <Reject> is the first verb in your response to the call, Twilio will not answer the call. If any other TwiML verbs are used before <Reject>, your application will receive the call and your account will be billed.

Issues with <Gather>

There is no test which can be done to definitively determine the origin of a problem with <Gather>. The best approach to take is to do everything possible to isolate the issue. Try the following: 

  1. Use several different phones from different carriers. If the issue occurs reliably, but only on phones from a particular carrier, you might want to contact that carrier directly to report the issue. If the problem occurs reliably on multiple telephones from multiple service providers, please contact Twilio support
  2. If the issue happens only intermittently, it may be due to environmental factors or the style of use from a particular user. Try to see if there is a particular user, phone or location that experiences this issue more often.
  3. Check how your application handles <Gather>. <Gather> may receive all of the inputs from your user, but your application may not properly handle the request at the URL specified in <Gather action="">. Be sure to check that action="" points to the correct location, and that your specified location can accept requests made with the method you are using.

For more help implementing <Gather>, please see this guide.

International Issues

Twilio supports calling worldwide, but international permissions must be explicitly enabled. You can enable international permissions here.

If your account is not yet set up for international dialing, you should request access. After your account has been granted access, revisit the Global Permissions page and enable any country you wish to call.

Other Tools and Add-Ons

Twilio Status

You can always check the real-time status of Twilio systems via the Twilio status page. If anything is wrong on our end, you'll see it there.

Voice Insights and Add-Ons

If you're looking for additional insights into your voice calls, you may want to consider Voice Insights,   which gives you use real-time data about call quality, carrier analytics, and WebRTC performance to proactively assist customers and minimize support time.

Twilio also offers a wide variety of add-ons that help you easily access partner technologies that let you do more with Twilio. You can see the entire catalog of add-ons in the marketplce, including Twilio Carrier Information and the #1 Robocall and Spam Blocking solution 

Contact Support

If you're still having trouble with your Twilio Voice calls, you can reach out to our support team for help.

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.