If you encounter SMS delivery delays, an important first step is to rule out any latency occurring within your application, or between your application and Twilio. Testing with the API Explorer in Console offers an easy way to do this. API Explorer allows you to send an SMS message directly from Twilio, so you’ll be able to tell whether the issue is related to your code, or something on Twilio’s end.
Notice: The API Explorer will reach its End of Life on December 15th, 2023, and will no longer be accessible after this date. For alternatives, please visit our API Reference docs.
How to send a message with the API Explorer
- Navigate to the "Create a Message" page in the API Explorer.
- 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.
- One of three results will happen
Message arrived within 30 seconds
If you received the message you sent via the API explorer instantly, then very likely Twilio is not receiving a valid request when you tried from your application, and there is most likely a problem with your code. You may 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.
- Try using the code snippet generated in the API Explorer in your application and see if that fixes the issue.
- Check your HTTP logs to see that the requests you made to Twilio resulted in 400 or 500 level 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.
If the message sent from your application did get delivered but always with a consistent delay, there may be a network issue between your server and Twilio’s API, which stopped Twilio from receive these requests immediately. Dig into your network logs and see if you can find anything.
Message arrived in more than 30 seconds
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".
When clicking into a specific message on the SMS Logs page, there is a “Delivery Steps” section that shows further insights into different stages the message goes through with detailed timestamps. For example, when the message request was created, for how long the message was queued on Twilio’s platform, and at what time the message was sent to our carrier partner for delivery. The “Delivery Steps” info provides valuable insights that help track down where the latency may come from.
Possible causes include:
- There is 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 Queue Insights page.
- 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).
In most cases, the API Explorer will either generate a 201 response or 400 response. See below for an explanation and help with each.
201 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 this:
If you get a 201 response, check the following:
- Verify the “To” phone number
- Is correct
- Has good reception, in which it may be just delayed.
- Can receive messages from other sources/senders.
- Is not roaming internationally as Twilio does not support international SMS roaming currently.
- Is not on a “do not contact” list. 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.
- Certain carriers may block 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 about carrier content filtering for more information.
- Try sending again. This 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.
400 response
If the request made to Twilio is invalid, you will receive a <code>400</code> 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. There should also be an error code and a link to a detailed description of the error code. Here are the most common errors:
You need to enable SMS permissions for this country on the Global SMS Permissions page.
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, or can only handle domestic SMS. This list shows which Twilio phone numbers are SMS enabled. All other Twilio phone numbers are not capable of sending SMS messages.
There are a few possible causes for this error:
- 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.
- You attempt to send from international Twilio numbers to +1 destinations (eg, United States, Canada). Twilio currently does not support this route and please use a local US or CA number instead.
- 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.
Find recent (within last 72 hours) the SMS Message SID for the message and send it along with a brief explanation of the tests you've already tried. It will also help if you can try performing the same tests on another phone.