Debugging Tools

Twilio offers several tools for investigating the interaction between Twilio and your application. If a message fails to go through, is delayed, or otherwise behaves unexpectedly, these tools should be your first stops for debugging.

How to use the Twilio 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:

How to find the Twilio Debugger in Runtime

Once in the debugger, you can dig into detailed logs. You can see which product was affected by an error or warning by the icon in the 'Product' column. 

Determine the product affected in the debugger

By clicking on an event in the debugger, you can see properties of the message that encountered an error, such as timestamps, your resource SID, any warnings or errors thrown by Twilio, and the full context of the message request and response.

Configure Custom Alerts

By default, Twilio will notify you via email of your 1st error on any given day. By setting your own alert triggers via the console, you can customize which error codes trigger alerts and how you receive those alerts:

Create a new alert trigger

Explore your Message Logs

If you encounter issues with message delivery, such as duplicate message delivery, the best way to begin debugging is by viewing your message logs.

Log into your Twilio account and navigate to the Programmable SMS dashboard.

How to get to the Programmable SMS dashboard

Then, click on the link for your SMS logs:

Find your SMS logs

Once you’re in your SMS logs, find the message where the problem occurred. Click the hyperlinked date to dig down into the details for this message. You’ll see messages that hit something other than a 200 are highlighted in yellow or red.

SMS Logs

As you can see above, each log line includes the number of message segments, the message status, TO and FROM numbers, as well as if any media was attached. To dig deeper into a log for a given message, click on the hyperlinked date. This will take you to the Message Details:

SMS Log Details

In the detailed view of the message log, you can find the Message SID (Twilio's unique identifier for this message), as well as the time the resource was created, TO and FROM numbers, Delivery Steps, and the Request Inspector.

Delivery Steps

The Delivery Steps section of this log will show you when the request was created, how long it was queued on Twilio's platform, and when it was sent out to our carrier partner for delivery. These factors can help you determine where an undelivered message failed, or investigate latency issues.

SMS logs: Delivery Steps

Request Inspector

The request inspector shows all requests and responses made when sending or receiving this message. You can easily see errors on requests by the color-coded status on the right of a request.

SMS Request Inspector

In the above response, we can see that we received a 502 response because Twilio was unable to connect to the webhook we set up for messages.

Test with the API Explorer

Another powerful tool for debugging messages is Twilio’s API Explorer. The API Explorer allows you to send an SMS message in the simplest way possible: directly from the Twilio console. This helps you figure out whether the issue you’re encountering is related to your code or if something has gone wrong on Twilio’s end.

To send a message with the API explorer:

  1. Navigate to the "Create a Message" page in the API Explorer.
  2. Fill out, at the minimum, the From, To and Body fields in the form. You may include any other data that you're trying to send, such as a media URL or status callback.
  3. Click the "Make Request" button and keep the page open so that you can investigate the response.

Send an SMS with the API Explorer

Error Codes

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

Contacting Support

Each message that Twilio sends is matched to a record in these logs and identified by a 34-character string starting with ‘SM’ for SMS or ‘MM’ for MMS. This is your Message SID. If you are unable to figure out what went wrong with your message, you can contact our stellar support team by filling out this form, including any message SIDs affected.

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.