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:
There are several ways to troubleshoot an undelivered SMS message.
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:
If the SMS isn't in your logs and your application code is generating an error:
If you can't find the SMS in your logs and you received an error from Twilio:
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
.
If the message is marked Undelivered
or Failed
in Twilio's logs:
The message is marked Sent
or Delivered
in the logs but wasn't sent to the 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:
Is your Twilio number SMS-enabled? Does it have a webhook configured?
Any number that shows the SMS icon can send and receive SMS messages:
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:
Are you expecting to receive SMSes from international numbers?
Are you roaming or off your network?
Are you expecting to receive SMSes from a short code?
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.