Debugging Common SMS Issues

There are several common issues users run into when sending or receiving SMS messages. This guide outlines a few of the most common problems and provides troubleshooting tips:

• My message wasn’t delivered
• I’m not receiving SMS messages on my Twilio phone number
• From/To pairs are violating blocked sender rules
• Why do I encounter duplicate messages?
• My messages are delayed

My message wasn’t delivered

There are several ways to troubleshoot an undelivered SMS message.

1. Check your Messaging logs for a record of the SMS request. If you don’t see a record of your message at all, the message likely encountered an error in your application or potentially with Twilio’s API:
   • You can try sending a test message with the API Explorer. This will validate if your TO and FROM numbers are active and accepting messages.
   • You can look at your error logs to see what error was caught, if any.
2. If the SMS isn’t in your logs and your application code is generating an error:
• You can find some sample requests for sending SMS messages in your language of choice here on our documentation. These sample requests can help isolate any syntax issues that may have cropped up in your code.
3. If you can’t find the SMS in your logs and you received an error from Twilio:
• If you received a 4XX response from Twilio’s API, Twilio encountered a problem and wasn’t able to send the message. You can look up the code you received in this list of errors.
4. If the message is marked Undelivered or Failed in Twilio’s logs:
• In this case, Twilio received a delivery receipt from one of our carriers indicating that the message was not delivered. This can happen for several reasons, including carrier content filtering or the availability of the destination phone.
5. The message is marked Sent or Delivered in the logs but wasn’t sent to the device:
• To further debug, check out the section below for troubleshooting tips when a message doesn’t arrive at your device.

Read more in the Troubleshooting Undelivered Twilio SMS Messages support article.

I’m not receiving SMS messages on my Twilio phone number

There are several questions you should ask if messages are not reaching your Twilio number:

1. Is your Twilio number SMS-enabled? Does it have a webhook configured?
• Log in to your Twilio account, navigate to the Phone Numbers section and click on Manage Numbers.
• Any number that shows the SMS icon can send and receive SMS messages:

  

• If there is no icon under SMS, your Twilio number does not have SMS capabilities. Click on Buy a Number to purchase an SMS-enabled Twilio number.
• Your number also needs to have a URL associated with it to receive incoming SMS. You can set up this webhook in the Console for any Twilio phone number you own:

  

2. Are you expecting to receive SMSes from international numbers?
   • Some international carriers aren’t able to successfully pass off SMS messages to Twilio’s network. Because of this, Twilio can’t guarantee that international messages will always be received.
   • If you’re receiving domestic but not international SMS messages, we recommend contacting the international sending carrier.
3. Are you roaming or off your network?
• Twilio can’t guarantee the deliverability of SMSes from roaming phone numbers. Twilio does not have the ability to determine whether or not the phone number you are sending messages from is roaming at the time.
4. Are you expecting to receive SMSes from a short code?
   • Twilio accounts can now be enabled to receive messages from short codes. This is an account-wide setting, which will apply to all long code numbers that belong to your Twilio account.
   • Your account must have a Twilio number from the same country as the short code from which you expect to receive messages. Short code numbers are always country-specific and can only communicate with numbers from the same country.
   • Please contact Twilio Support to have this option enabled on your account. It’s important to note that even when this feature is enabled, we can’t always guarantee delivery of these incoming messages due to factors outside of our control.

From/To pairs violating blocked sender rules

When sending messages, you may see a response from Twilio about the message’s From/To pair violating delivery rules. The Twilio API returns this message if you attempt to send an SMS or MMS to a recipient who has previously replied STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, or QUIT to your Twilio number. You will not be charged for this send attempt.

When a user opts out of receiving communications from a phone number that belongs to a Messaging Service, they are also opted out of all messages sent from that particular Messaging Service.

If you are to send messages to a recipient who has opted out this way, they must first text START or YES to your Twilio number to opt in again.

Why do I encounter duplicate messages?

The best way to begin debugging duplicate message issues is to review your Messaging logs. You should look for a record of the message in question, as well as other messages that are duplicates that were sent within seconds of each other.

If you find duplicate messages sent within a few seconds of each other in your logs, it means that Twilio sent multiple messages to the carrier. This almost always means that Twilio received multiple POST requests from your application. Please check the HTTP request logs on your server to examine the requests you sent to Twilio.

It is extremely rare for Twilio’s system to create a duplicate message without receiving a POST from your application. If you’ve checked your server logs and only see one request to Twilio, please let us know by contacting support with the SIDs of the duplicated messages.

If you find only one message in your logs, it means that Twilio sent just one message to the carrier and the duplication happened within the carrier’s system. Users of all types of phones do occasionally receive duplicate messages, typically as the result of a safeguard that carriers implement when they suspect there may have been a service disruption. Duplicate messages may also occur when the recipient is roaming.

If duplicate messages occur for an extended time and with several different recipient carriers, please let us know by collecting the message records of the duplicated messages and contacting support.

My messages are delayed

To troubleshoot issues with delayed messages or other delivery issues, start by testing your numbers with the API Explorer. First, create a message, filling out the From, To, and Body fields and any other relevant fields. Click Make Request and keep the page open so you can examine the response when it arrives.

When you send a message via the API Explorer, one of three things will happen:

1. The message arrives within 30 seconds.
   • The problem with your messages most likely comes from your application code. Check that:
     • The To and From values you used in your code match those you used in the API Explorer.
     • Try using the code snippet generated in the API Explorer in your application and see if that fixes the issue.
     • Check your HTTP logs and verify the requests you made to Twilio did not result in 40x or 50x errors.
     • 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.
2. The message arrives more than 30 seconds later.
   • SMS messages sent from Twilio typically arrive at their destination in 5-10 seconds, depending on the country and the carrier. If a message takes more than 30 seconds for delivery, we consider it ‘delayed’.
     
     • Look in your Messaging logs under Delivery Steps to see more detailed timestamps, including when the request was created, how long it stayed queued on Twilio’s platform, and when we sent it to our carrier partner for delivery. This information can help you track down where latency may originate.
     • A large number of queued messages on the From number may increase latency. For more information on latency, see this article which describes Twilio’s rate limits.
     • There may be congestion on downstream carrier networks. These problems usually resolve automatically when downstream traffic starts to clear.
3. No message arrives.
• If the API Explorer generated a 201 response, check the following:
  1. Verify that the To phone number:
  • Is valid and active.
  • Has good reception. If not, the message may just be delayed.
  • Can receive messages from other sources and senders.
  • Is not roaming internationally.
  • Is not on a ‘do not contact’ list.
  • Is not blocked by the carrier. If you are sending the message from a Twilio long code, try sending from a different Twilio long code. If the message is properly received, you’ve likely encountered a carrier’s volume threshold on your original long code. See this FAQ for more information.
  2. Try sending the message again. This is often the best way to verify the problem. If the message still doesn’t send, contact our support team with the SMS Message SIDs for each attempt that does not arrive. These SIDs are listed in the API explorer’s response.
• If the API Explorer generated a 404 response Twilio was not able to send the message.
  • Any messages that return a 404 response should include an error code and a link to a detailed description of the error code. You can find information on all of our error codes here.

For building messaging applications at scale, we have a document detailing best practices to get you started in a way that minimizes latency and shows you how to monitor your messages with Messaging Insights.