Track the Message Status of Outbound Messages
This guide shows you how to use Twilio's status callbacks to track changes of the message status of outbound messages you send with Programmable Messaging.
Message status changes occur throughout the lifecycle of a message from creation, through sending, to delivery, and even read receipt for supporting messaging channels.
Info
The guide focuses on outbound messages created using the Message Resource of the Programmable Messaging REST API and covers the necessary considerations when using a Messaging Service.
Before you dive into this guide, make sure you're familiar with the following:
- You should know how to send a message using the Programmable Messaging API. You can follow a Messaging Quickstart in the programming language of your choice.
- Review our guide Outbound Message Status in Status Callbacks to understand for which status changes Twilio sends a status callback request.
- If your use case involves the sending of high volumes of messages or message scheduling, then you should know what a Messaging Service is and how to use it when sending a message .
- The status callbacks covered in this guide are Twilio webhooks. Check out our guide to Getting Started with Twilio Webhooks . Find other webhook pages, such as a security guide and FAQ in the Webhooks section of the docs.
Note: The code samples in this guide require some local setup steps. Select your language of choice below to learn how to set up your development environment.
Let's get started!
Tracking the message status of an outbound message is a two-step process
In order to track the message status of an outbound message, you must first create an API endpoint that:
- Is served under a publicly accessible URL, the status callback URL, and
- Implements a status callback handler for Twilio's message status callback HTTP requests.
Warning
A status callback URL must contain a valid hostname. Underscores are not allowed.
How you implement your status callback endpoint depends on your use case and technology preferences. This may mean you
- Create and host a small web application to handle the requests in the programming language and framework of your choice
- Add an additional new endpoint to your existing web application
- Use a serverless framework like Twilio Serverless Functions .
Twilio sends status callback requests as HTTP POST requests with a Content-Type of application/x-www-form-urlencoded.
Warning
The properties included in Twilio's request to the StatusCallback URL vary by messaging channel and event type and are subject to change.
Twilio occasionally adds new properties without advance notice.
When integrating with status callback requests, it is important that your implementation is able to accept and correctly run signature validation on an evolving set of parameters.
Twilio strongly recommends using the signature validation methods provided in the Helper Libraries and not implementing your own signature validation.
In a status callback request, Twilio provides a subset of the standard request properties, and additionally MessageStatus and ErrorCode. These properties are described in the table below.
| Property | Description |
|---|---|
MessageStatus | The status of the Message resource at the time the status callback request was sent. |
ErrorCode | If an error occurred (i.e. the MessageStatus is failed or undelivered), this property provides additional information about the failure. |
For example, a status callback request sent when the Message resource for an outbound SMS changes status to sent, may contain the following content:
_10"AccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"_10"From": "+15017250604"_10"MessageSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"_10"MessageStatus": "sent"_10"SmsSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"_10"SmsStatus": "sent"
For most SMS/MMS Messages that have a Status of delivered or undelivered, Twilio's request to the StatusCallback URL contains an additional property:
| Property | Description |
|---|---|
RawDlrDoneDate | This property is a passthrough of the Done Date included in the DLR (Delivery Receipt) that Twilio received from the carrier. The value is in YYMMDDhhmm format.
|
If the Message resource uses WhatsApp or another messaging channel, Twilio's request to the StatusCallback URL contains additional properties. These properties are listed in the table below.
| Property | Description |
|---|---|
ChannelInstallSid | The Installed Channel SID that was used to send this message |
ChannelStatusMessage | The error message returned by the underlying messaging channel if Message delivery failed. This property is present only if the Message delivery failed. |
ChannelPrefix | The channel-specific prefix identifying the messaging channel associated with this Message |
EventType | This property contains information about post-delivery events. If the channel supports read receipts (currently WhatsApp only), this property's value is READ after the recipient has read the message. |
Info
You may want to explore how status callback requests behave before working through your actual implementation. A light-weight way to accomplish this goal is to use Twilio Serverless Functions and inspect the status callbacks in the Console using the Function Editor's debugging feature.
- Log into your Twilio Account
-
If you do not already have a suitable
Functions and Assets Service
in your Console, you can
create a new service
for your status callback handler endpoint. Let's assume you created a new service under the name
status-callback-prototyping. -
From your service go to the
Functions Editor
to
Add
a new Function e.g. under the path
/message-statuswith the following handler code:
_10// Log Status Callback requests_10_10exports.handler = function(context, event, callback) {_10 console.log("Invoked with: ", event);_10 return callback(null, "OK");_10};
By default your new serverless function is created as a protected endpoint, which means Twilio Serverless performs signature validation to ensure only valid Twilio requests invoke your handler.
- Save the new function.
- Deploy your new serverless function by pressing Deploy All .
- Change the toggle control above the bottom-right corner logging window to Live logs on .
-
Click on the
Copy URL
link above the bottom-right logging window to copy the URL for your prototype status callback endpoint into your clipboard. The copied URL would look something like this:
https://status-callback-prototyping-1234.twil.io/message-status.
You can now use your copied status callback URL in the next step of this guide: Step 2. Send a message with status callback URL.
- Once you sent a message, you can inspect the logged status callback request in the bottom-right logging window of the Functions Editor in Console.