How can I troubleshoot if an SMS message sent from Twilio doesn’t arrive?
You’ve tried sending an SMS message, but it didn’t arrive. Fear not! This article is designed to help you walk through troubleshooting steps to diagnose, and hopefully fix, the problem.
Try sending in the API Explorer
Using the API Explorer allows you to send an SMS message in the simplest way possible: directly from Twilio. When you encounter SMS delivery problems, testing with the API Explorer should always be your first debugging step. Altering your code to “fix” a problem before you are sure that the problem is actually with your code may only increase the number of things which you need to fix later.
- Visit the API Explorer’s “Send SMS” page.
- Fill out the “From”, “To” and “Body” fields in the form.
- Click the “Make Request” button and keep the page open so that you can look at the response later.
- Check to see if you received the message.
- I received the message within 30 seconds.
- I received the message, but it took more than 30 seconds.
- I did not receive the message.
If you received the message you sent via the API explorer, then Twilio is probabally not receiving a valid request from your application and there is most likely a problem with your code. You will probabally want to check the following:
- Check to make sure that the “To” and “From” values you used in your code match those you used in the API Explorer.
- Check your HTTP logs to see that the request you are making to Twilio is valid. If a request is not valid, Twilio will respond with a 4XX response.
- Be sure that you are using the correct Account SID and Auth Token. Please note that using the Test Credentials will produce a response indicating that the message has been sent, but the message will not actually be sent.
SMS messages sent from Twilio typically arrive at their destination within 5 to 10 seconds depending on the country and the carrier. If a message takes more than 30 seconds, we consider the message to have been “delayed”.
- There is congestion on downstream carrier networks. These types of problems should resolve themselves when downstream traffic starts to clear. Twilio does not have the ability to troubleshoot these issues. However, if you are noticing reproducible message delays on multiple phones over the course of several days, please let us know so that we can alert the affected carrier(s).
- There are a large number of queued messages on the “From” number you are using. If the “From” number already has a large number of messages queued, additional messages you try to send are added to the queue rather than being sent immediately. This article has more information on Twilio’s rate limits. You can check to see if this is the issue by looking at the SMS usage charts to see if there were a large number of messages sent at the same time you tried to send the test message.
Check the Response
When you clicked “Make Request”, you sent an HTTP POST request to Twilio instructing Twilio to send an SMS. If the request was valid, Twilio will send the message and return a
201 response which contains an SMS Message “SID”. The SMS Message “SID” is the unique ID for the message, and is only created for successful requests. It should look something like the image on the right.
If the request made to Twilio is invalid, you will receive a
400 response. This means that Twilio was not able to send the message. There will also be a link in the response to the specific reason why the message could not be sent.
- Is it the “To” phone number correct? It’s always worth checking…
- Does the “To” phone have reception? If not, try moving to a location with reception and try again.
- Does the “To” phone receive SMS messages sent from other sources? Try using another phone to send the “To” phone a test message.
- Is the phone you are sending to roaming internationally? Twilio is not able to support international roaming for SMS at this time.
- Is the “To” phone number on a “Do Not Contact” list for the country or carrier? For Example, India has a particularly strict national Do Not Contact list. The “To” number will need to be removed from any Do Not Contact lists before it can receive SMS messages from Twilio.
- Does the country you are sending an SMS message to have a special prefix which must be used in order to send an SMS? Mexico and Argentina are examples of this.
- Did the end number’s provider filter it out? Certain carriers will blacklist numbers that are sending a high volume of SMS. Try sending the same message from another Twilio long code. If it is properly received, you’ve likely encountered a carrier’s volume threshold. Check out this FAQ for more information.
- Try multiple times. There’s no harm in trying multiple times. Trying again is often the best way to prove to yourself and those helping you that you are doing everything correctly. Be sure to copy down the SMS Message SIDs for each attempt which doesn’t arrive.
If you’ve checked all of the possible explainations above and still don’t know why the message didn’t arrive, find the SMS Message SID for the message and send it along with a brief explanation of the tests you’ve already tried to Twilio’s Customer support. It will also help if you can try performing the same tests on another phone. We need these SMS Message SIDs to be recent because many carriers only keep their logs for 72 hours.
If you’ve received a
400 response from the API, that means that Twilio encountered a problem and was unable to send your message. There should also be an error code and a link to a detailed description of the error code. Here are the most common errors.
- Error – 21408: You need to enable SMS permissions for this country on the Global SMS Permissions page.
- Error – 21606: You are attempting to use a “From” number which is not capable of sending SMS messages to your “To” number. You might be trying to send SMS from a phone number which is only enabled for voice. This list shows which Twilio phone numbers are SMS enabled. All other Twilio phone numbers are not capable of sending SMS messages.
- Error – 21612. This error can have two explanations:
- The carrier you are sending to is not a supported carrier. Twilio supports most carriers worldwide, but there are still carriers which we do not yet support. To determine if Twilio supports a particular carrier, please search for the country on the SMS Pricing page and scroll to the section labeled “All Pricing for…” If the carrier does not appear on that list, Twilio cannot send SMS messages to that carrier at this time.
- The “To” phone number is not properly formatted in E.164.
Contacting Twilio Support
Please feel free to contact Twilio’s support team for help with SMS troubleshooting. Your message should contain the following information:
- A brief explanation of what you are trying to do.
- A brief explanation of the tests you’ve tried so far.
- SMS Message SIDs for messages which you want us to investigate. In the event that we need to get information about the messages for one of our partner carriers, we will need to provide them with fresh examples of SMS SIDs to investigate. Many carriers only keep their logs for 72 hours, so it’s important that the examples you send us are as fresh as possible.