Debugging Common Issues with SMS

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 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.

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:

     Expand image

   • 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:

     Expand image

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.

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.

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.