Track the Message Status of Outbound Messages

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.

• Node.js
• Python
• C# and ASP.NET MVC
• PHP
• Java
• Ruby
• Go

Let's get started!

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

1. Set up a status callback endpoint

   • How are status callback requests sent?
   • Implement a status callback handler (simplified example)

2. Send a message with status callback URL

   • Scenario 1: No Messaging Service
   • Scenario 2: Messaging Service used

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.

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.

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.

For example, a status callback request sent when the Message resource for an outbound SMS changes status to sent, may contain the following content:

1
"AccountSid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2
"From": "+15017250604"
3
"MessageSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"
4
"MessageStatus": "sent"
5
"SmsSid": "SM1342fe1b2c904d1ab04f0fc7a58abca9"
6
"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:

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.

(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 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:

Copy code block

1
// Log Status Callback requests
2

3
exports.handler = function(context, event, callback) {
4
  console.log("Invoked with: ", event);
5
  return callback(null, "OK");
6
};

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.

4. Save the new function.

5. Deploy your new serverless function by pressing Deploy All.

6. Change the toggle control above the bottom-right corner logging window to Live logs on.

7. 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.

8. 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.

Expand image

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.

1
const http = require('http');
2
const express = require('express');
3
const bodyParser = require('body-parser');
4

5
const app = express();
6

7
app.use(bodyParser.urlencoded({ extended: true }));
8

9
app.post('/message-status', (req, res) => {
10
  const messageSid = req.body.MessageSid;
11
  const messageStatus = req.body.MessageStatus;
12

13
  console.log(`SID: ${messageSid}, Status: ${messageStatus}`);
14

15
  res.sendStatus(200);
16
});
17

18
http.createServer(app).listen(1337, () => {
19
  console.log('Express server listening on port 1337');
20
});

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.

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

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "McAvoy or Stewart? These timelines can get so confusing.",
13
    from: "+15017122661",
14
    statusCallback: "http://example.com/MessageStatus",
15
    to: "+15558675310",
16
  });
17

18
  console.log(message.body);
19
}
20

21
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "McAvoy or Stewart? These timelines can get so confusing.",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+15017122661",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+15558675310",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

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.

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

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "McAvoy or Stewart? These timelines can get so confusing.",
13
    messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
14
    to: "+15558675310",
15
  });
16

17
  console.log(message.body);
18
}
19

20
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "McAvoy or Stewart? These timelines can get so confusing.",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+14155552345",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+15558675310",
27
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
28
}

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

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function createMessage() {
11
  const message = await client.messages.create({
12
    body: "McAvoy or Stewart? These timelines can get so confusing.",
13
    messagingServiceSid: "MG9752274e9e519418a7406176694466fa",
14
    statusCallback: "http://example.com/MessageStatus",
15
    to: "+15558675310",
16
  });
17

18
  console.log(message.body);
19
}
20

21
createMessage();

1
{
2
  "account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "api_version": "2010-04-01",
4
  "body": "McAvoy or Stewart? These timelines can get so confusing.",
5
  "date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
6
  "date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
7
  "date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
8
  "direction": "outbound-api",
9
  "error_code": null,
10
  "error_message": null,
11
  "from": "+14155552345",
12
  "num_media": "0",
13
  "num_segments": "1",
14
  "price": null,
15
  "price_unit": null,
16
  "messaging_service_sid": "MG9752274e9e519418a7406176694466fa",
17
  "sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
18
  "status": "queued",
19
  "subresource_uris": {
20
    "media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"
21
  },
22
  "tags": {
23
    "campaign_name": "Spring Sale 2022",
24
    "message_type": "cart_abandoned"
25
  },
26
  "to": "+15558675310",
27
  "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:

• Read our guide Best Practices for Messaging Delivery Status Logging for advanced considerations when implementing a production-grade status logging solution.
• Explore our guide How to Optimize Message Deliverability with Message Feedback.
• See how Message Feedback supports the Messaging Insights "One-time Password (OTP) Conversion Report". Learn how to analyze the effectiveness of messages sent to provide two-/multi-factor authentication (2FA, MFA) codes or other one-time passwords for user authentication or account verification.
• Shorten links in messages with your own company-branded domain and track click-through-rates with Link Shortening.