Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

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.

(information)

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 begin

before-you-begin page anchor

Before you dive into this guide, make sure you're familiar with the following:

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!


How to track outbound message status

how-to-track-outbound-message-status page anchor

Tracking the message status of an outbound message is a two-step process

  1. Set up a status callback endpoint

  2. Send a message with status callback URL


Step 1. Set up a status callback endpoint

step-1-set-up-a-status-callback-endpoint page anchor

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)

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 .

How are status callback requests sent?

how-are-status-callback-requests-sent page anchor

Twilio sends status callback requests as HTTP POST requests with a Content-Type of application/x-www-form-urlencoded.

(warning)

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.

PropertyDescription
MessageStatusThe status of the Message resource at the time the status callback request was sent.
ErrorCodeIf 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"

SMS/MMS

smsmms page anchor

For most SMS/MMS Messages that have a Status of delivered or undelivered, Twilio's request to the StatusCallback URL contains an additional property:

PropertyDescription
RawDlrDoneDateThis 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.
  • YY is last two digits of the year (00-99)
  • MM is the two-digit month (01-12)
  • DD is the two-digit day (01-31)
  • hh is the two-digit hour (00-23)
  • mm is the two-digit minute (00-59).
Learn more on the "Addition of RawDlrDoneDate to Delivered and Undelivered Status Webhooks" Changelog page(link takes you to an external page).

WhatsApp and other messaging channels

whatsapp-and-other-messaging-channels page anchor

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.

PropertyDescription
ChannelInstallSidThe Installed Channel SID that was used to send this message
ChannelStatusMessageThe error message returned by the underlying messaging channel if Message delivery failed. This property is present only if the Message delivery failed.
ChannelPrefixThe channel-specific prefix identifying the messaging channel associated with this Message
EventTypeThis 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.

Implement a status callback handler (simplified example)

implement-a-status-callback-handler-simplified-example page anchor
(information)

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.

  1. Log into your Twilio Account
  2. If you do not already have a suitable Functions and Assets Service(link takes you to an external page) 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 .
  3. From your service go to the Functions Editor to Add a new Function e.g. under the path /message-status with the following handler code:

_10
// Log Status Callback requests
_10
_10
exports.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.

  1. Save the new function.
  2. Deploy your new serverless function by pressing Deploy All .
  3. Change the toggle control above the bottom-right corner logging window to Live logs on .
  4. 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.

  1. 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.
Serverless Functions Status Callback - Functions Editor.

Your response to Twilio's status callback request should have an HTTP status code of 200 (OK). No response content is required.

What your status callback handler should do when receiving a status callback request, depends on your use case.

The following simplified web application illustrates how you could log the MessageSid and MessageStatus of outbound messages as they move through their lifecycle.

(warning)

Warning

Status callback requests are HTTP requests and are therefore subject to differences in latency caused by changing network conditions.

Status callback requests are sent in accordance with the message status transitions described in the guide Outbound Message Status in Status Callbacks. Some of these status transitions may occur in quick succession.

As a result, there is no guarantee that the status callback requests always arrive at your endpoint in the order they were sent.

You should bear this consideration in mind when implementing your status callback handler.

(information)

Info

Read our guide Best Practices for Messaging Delivery Status Logging for advanced considerations when implementing a production-grade status logging solution.

Handle a Message status callback request

handle-a-message-status-callback-request page anchor

Log the Message SID and MessageStatus received from a status callback request

Node.js
Python
C#
Java
Go
PHP
Ruby

_20
const http = require('http');
_20
const express = require('express');
_20
const bodyParser = require('body-parser');
_20
_20
const app = express();
_20
_20
app.use(bodyParser.urlencoded({ extended: true }));
_20
_20
app.post('/message-status', (req, res) => {
_20
const messageSid = req.body.MessageSid;
_20
const messageStatus = req.body.MessageStatus;
_20
_20
console.log(`SID: ${messageSid}, Status: ${messageStatus}`);
_20
_20
res.sendStatus(200);
_20
});
_20
_20
http.createServer(app).listen(1337, () => {
_20
console.log('Express server listening on port 1337');
_20
});


Step 2. Send a message with status callback URL

step-2-send-a-message-with-status-callback-url page anchor

In Step 1 you implemented a status callback handler which is publicly available at your status callback URL.

In this step you learn how to ensure Twilio sends status callback requests to your status callback URL for outbound messages.

How you do this may depend on whether you use a Messaging Service to send messages or not.

Scenario 1: No Messaging Service

scenario-1-no-messaging-service page anchor

For Twilio to send status callback requests, you need to provide your status callback URL in the StatusCallback parameter of each message for which you want to track the MessageStatus.

To get the following code sample to run, replace the following information:

  1. Replace the From phone number with one of your Twilio numbers
  2. Replace the To number with your mobile number
  3. Replace the StatusCallback URL with your status callback URL

Send a Message without Messaging Service with a StatusCallback URL

send-a-message-without-messaging-service-with-a-statuscallback-url page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
import twilio from "twilio";
_17
_17
// Find your Account SID and Auth Token at twilio.com/console
_17
// and set the environment variables. See http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = twilio(accountSid, authToken);
_17
_17
const message = await client.messages.create({
_17
body: "McAvoy or Stewart? These timelines can get so confusing.",
_17
from: "+15017122661",
_17
statusCallback: "http://example.com/MessageStatus",
_17
to: "+15558675310",
_17
});
_17
_17
console.log(message.body);

Output

_28
{
_28
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"api_version": "2010-04-01",
_28
"body": "McAvoy or Stewart? These timelines can get so confusing.",
_28
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"direction": "outbound-api",
_28
"error_code": null,
_28
"error_message": null,
_28
"from": "+15017122661",
_28
"num_media": "0",
_28
"num_segments": "1",
_28
"price": null,
_28
"price_unit": null,
_28
"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"status": "queued",
_28
"subresource_uris": {
_28
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
_28
},
_28
"tags": {
_28
"campaign_name": "Spring Sale 2022",
_28
"message_type": "cart_abandoned"
_28
},
_28
"to": "+15558675310",
_28
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_28
}

Scenario 2: Messaging Service used

scenario-2-messaging-service-used page anchor

Messaging Services can be configured to have a service-level Delivery Status Callback. When creating a new Messaging Service in Console, you can specify this service-level Delivery Status Callback in Step 3 - Set up Integrations.

You can use the status callback URL from Step 1 of this guide for this Delivery Status Callback integration. If you do so, you do not have to provide the status callback URL as a message-specific parameter.

Alternatively, you can provide a message-specific status callback URL in the StatusCallback parameter for a message created with the Messaging Service.

Which of these two options is more appropriate depends on your use case.

Option 1 - Use Service-level Delivery Status Callback

option-1---use-service-level-delivery-status-callback page anchor

To get the following code sample to run, replace the following information:

  1. Replace the MessagingServiceSid with the SID of one of your Messaging Services that has a Deliver Status Callback integration configured in Console
  2. Replace the To number with your mobile number

Send a Message using Messaging Service with Delivery Status Callback Integration

send-a-message-using-messaging-service-with-delivery-status-callback-integration page anchor

Use the Delivery Status Callback configured for the Messaging Service in Console. No need to provide a StatusCallback parameter with each Message creation.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_16
// Download the helper library from https://www.twilio.com/docs/node/install
_16
import twilio from "twilio";
_16
_16
// Find your Account SID and Auth Token at twilio.com/console
_16
// and set the environment variables. See http://twil.io/secure
_16
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_16
const authToken = process.env.TWILIO_AUTH_TOKEN;
_16
const client = twilio(accountSid, authToken);
_16
_16
const message = await client.messages.create({
_16
body: "McAvoy or Stewart? These timelines can get so confusing.",
_16
messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
_16
to: "+15558675310",
_16
});
_16
_16
console.log(message.body);

Output

_28
{
_28
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"api_version": "2010-04-01",
_28
"body": "McAvoy or Stewart? These timelines can get so confusing.",
_28
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"direction": "outbound-api",
_28
"error_code": null,
_28
"error_message": null,
_28
"from": "+14155552345",
_28
"num_media": "0",
_28
"num_segments": "1",
_28
"price": null,
_28
"price_unit": null,
_28
"messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
_28
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"status": "queued",
_28
"subresource_uris": {
_28
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
_28
},
_28
"tags": {
_28
"campaign_name": "Spring Sale 2022",
_28
"message_type": "cart_abandoned"
_28
},
_28
"to": "+15558675310",
_28
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_28
}

Option 2 - Use Message-specific status callback URL

option-2---use-message-specific-status-callback-url page anchor
(information)

Info

If your Messaging Service has a service-level Delivery Status Callback configured in the Console and you provide a messages-specific StatusCallback URL as shown in the next code sample, Twilio sends the status callback requests to the message-specific StatusCallback URL.

To get the following code sample to run, replace the following information:

  1. Replace the MessagingServiceSid with the SID of one of your Messaging Services
  2. Replace the To number with your mobile number
  3. Replace the StatusCallback URL with your status callback URL

Send a Message using Messaging Service and StatusCallback URL

send-a-message-using-messaging-service-and-statuscallback-url page anchor

Use a Messaging Service and provide a message-specific StatusCallback URL as a parameter.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_17
// Download the helper library from https://www.twilio.com/docs/node/install
_17
import twilio from "twilio";
_17
_17
// Find your Account SID and Auth Token at twilio.com/console
_17
// and set the environment variables. See http://twil.io/secure
_17
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_17
const authToken = process.env.TWILIO_AUTH_TOKEN;
_17
const client = twilio(accountSid, authToken);
_17
_17
const message = await client.messages.create({
_17
body: "McAvoy or Stewart? These timelines can get so confusing.",
_17
messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
_17
statusCallback: "http://example.com/MessageStatus",
_17
to: "+15558675310",
_17
});
_17
_17
console.log(message.body);

Output

_28
{
_28
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_28
"api_version": "2010-04-01",
_28
"body": "McAvoy or Stewart? These timelines can get so confusing.",
_28
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_28
"direction": "outbound-api",
_28
"error_code": null,
_28
"error_message": null,
_28
"from": "+14155552345",
_28
"num_media": "0",
_28
"num_segments": "1",
_28
"price": null,
_28
"price_unit": null,
_28
"messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
_28
"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
_28
"status": "queued",
_28
"subresource_uris": {
_28
"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
_28
},
_28
"tags": {
_28
"campaign_name": "Spring Sale 2022",
_28
"message_type": "cart_abandoned"
_28
},
_28
"to": "+15558675310",
_28
"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
_28
}


Now that you know how to track the message status of your outbound messages, check out the resources below for additional information and related Twilio product documentation:


Rate this page: