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.
Is there a record of Twilio sending your message?
Twilio’s request to send an SMS will create a record in your Twilio account’s logs, which you can view here.
If you aren’t seeing a record of your message being sent at all, then it’s likely it ran into an error with your application or with Twilio’s API. You can learn more about adding error logging to your application here, or you can try sending a test message via our API Explorer, which sends an SMS in the simplest way possible: directly through Twilio.
If no SMS is found in your logs and your application code is generating an error:
You can find some sample requests for sending SMS in your language of choice here. These will help isolate any potential syntax issues that would crop up in your code.
If there is no SMS in your logs and you received an error from Twilio:
If you’ve received a
4XX response from Twilio’s API, 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. Two common reasons for this:
- 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.
- You might be trying to send SMS from a number you have verified with Twilio. Twilio will only allow you to do this with phone calls, not SMS. You can learn more here.
- 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 SMS 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.
- Error-20003: 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.
If the message is “Undelivered” or “Failed” in Twilio’s logs:
If your message is marked as undelivered or failed, then Twilio has received a delivery receipt indicating that the message was not delivered. This can happen for a number of reasons, including carrier content filtering, availability of the destination phone, etc.
If your message is marked “Sent” or “Delivered” in Twilio’s logs but wasn’t delivered to the device:
- 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.