Objective 

Twilio provides Programmable SMS outbound message status tracking with Status Callbacks. These callbacks can be helpful to see if a message has been delivered, failed, or ran into some other delivery issues. They also allow you to build advanced analytics to easily see the state of all messages.

What is a Status Callback URL?

A Status Callback URL is a webhook that you can define on a Messaging Service or in an API Request where updates are posted when a message changes status.

You can find more detailed information on Status Callback URLs in our product documentation here.

Which statuses does a message go through?

Once a message is created, it progresses through multiple statuses until it is finally completed. The statuses that a message goes through vary depending on the channel, whether you are using a Messaging Service and if the message is scheduled or not.

You can find a detailed flowchart of the statuses a message goes through in each scenario here.

For information on what each status means, see our article on Twilio SMS and MMS Statuses and their Meanings.

Product 

Programmable Messaging 

Procedure

How to Request Status Callbacks

Status Callback URLs can be set in two ways:

1. In the StatusCallback parameter of your API Request to send a message
2. In a Messaging Service's "Delivery Status Callback" setting in the Twilio Console under "Messaging -> Services -> MessagingServiceName -> Integration"

For a relevant status change (see here for which statuses trigger a callback), Twilio will make an asynchronous webhook request to your Status Callback URL with the new status, as well as several other helpful parameters.

Below is an example of how to set the StatusCallback parameter in your API Request:

curl -X POST https://api.twilio.com/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages.json \
--data-urlencode "To=+13105555555" \
--data-urlencode "From=+12125551234" \
--data-urlencode "Body=Hello from Twilio" \
--data-urlencode 'StatusCallback=https://www.mysite.com/sms/callback' \
-u "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX:your_auth_token"

This example will transmit the message "Hello from Twilio" from the sender (212) 555-1234 (+12125551234) to the destination number at (310) 555-5555 (+13105555555). To make this script work for you, make the following updates, and then paste it into a terminal window:

• Line 1 update with your Twilio Account SID (in place of ACXXXXXXXXXXX)
• Line 2 update with a valid destination number
• Line 3 update with a valid sender number
• Line 4 update with the desired message body
• Line 5 update with your Status Callback url
• Line 6 update with your Account SID and Auth Token.

For an in depth guide on tracking your message's delivery statuses, see our product documentation here.