Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Best Practices for SMS Message Logging

Financial regulations require some companies to maintain a record of all communications, including unsuccessful attempts.

This best practices documentation focuses on logging for Mobile Terminated/Outbound messaging, but the process is similar for Inbound messaging.

How Twilio Message Delivery Status Works

When you first make a request to the Twilio SMS API, Twilio will respond synchronously with either success (200) or failure (400) HTTP status code. If the request was successful, Twilio will return the Message SID in the response.

The Message SID is your record that a message was created and has been accepted by Twilio for processing. Twilio recommends that you store this Message SID along with the current state of the message at the time Twilio returned the Message SID to you. The initial state of the message will be either Accepted or Queued.

Initial message response

Example Outbound Message Response

    "sid": "SM4262411b90e5464b98a4f66a49c57a97",
    "date_created": "Wed, 07 Feb 2018 17:46:52 +0000",
    "date_updated": "Wed, 07 Feb 2018 17:46:52 +0000",
    "date_sent": null,
    "account_sid": "AC0db966d80e9f1662da09c61287f8bba1",
    "to": "+15622089096",
    "from": null,
    "messaging_service_sid": "MG4d9d720b38f7892254869fabdca51e69",
    "body": "Test",
    "status": "accepted",
    "num_segments": "0",
    "num_media": "0",
    "direction": "outbound-api",
    "api_version": "2010-04-01",
    "price": null,
    "price_unit": null,
    "error_code": null,
    "error_message": null,
    "uri": "/2010-04-01/Accounts/AC0db966d80e9f1662da09c61287f8bba1/Messages/SM4262411b90e5464b98a4f66a49c57a97.json",
    "subresource_uris": {
        "media": "/2010-04-01/Accounts/AC0db966d80e9f1662da09c61287f8bba1/Messages/SM4262411b90e5464b98a4f66a49c57a97/Media.json"

Message Statuses

Your message goes through multiple stages while Twilio processes it (see all message statuses).

Message Status

There are two ways for a user to get status updates on a message:

  • poll the API
  • receive a Status Callback.

Message Status Order

For added context, the following are the possible delivery statuses of the message, in order:

  • Accepted
  • Queued
  • Sending
  • Sent / Failed
  • Delivered / Undelivered

Poll the API

At any point after the Message SID has been returned, you can make a GET request (poll) to the Twilio API using the Message SID to determine the status of the message. Twilio will return the message record including the message status.

See the API Documentation for a Message Resource on how to retrieve the message status and other attributes. This works fine for small-volume use cases and ad hoc analysis, but for large-scale logging, you should use status callbacks.

Receive a status callback

Using the Status Callback URL provided when the message request was submitted, Twilio will send Asynchronous status updates (Failed, Sent, Delivered, Undelivered). Each status callback will contain the Message SID and the current status of the message.

Sample status callbacks

Example Callback for Sent

MessageStatus: sent
MessageSid: SM4262411b90e5464b98a4f66a49c57a97
MessagingServiceSid: MG4d9d720b38f7892254869fabdca51e69
AccountSid: AC0db966d80e9f1662da09c61287f8bba1
From: +16232320112
ApiVersion: 2010-04-01
To: +15622089096
SmsStatus: sent
SmsSid: SM4262411b90e5464b98a4f66a49c57a97

Example Callback for Queued

MessageStatus: queued
MessageSid: SM4262411b90e5464b98a4f66a49c57a97
MessagingServiceSid: MG4d9d720b38f7892254869fabdca51e69
AccountSid: AC0db966d80e9f1662da09c61287f8bba1
From: +16232320112
ApiVersion: 2010-04-01
To: +15622089096
SmsStatus: queued
SmsSid: SM4262411b90e5464b98a4f66a49c57a97

Example Callback for Delivered

MessageStatus: delivered
MessageSid: SM4262411b90e5464b98a4f66a49c57a97
MessagingServiceSid: MG4d9d720b38f7892254869fabdca51e69
AccountSid: AC0db966d80e9f1662da09c61287f8bba1
From: +16232320112
ApiVersion: 2010-04-01
To: +15622089096
SmsStatus: delivered
SmsSid: SM4262411b90e5464b98a4f66a49c57a97

High-volume callback data storage using Twilio Functions

For customers sending millions of messages in a given day, handling a high volume of callbacks can present an operational risk. Imagine sending 10M messages and receiving 20M callbacks. Using Twilio Functions, you can configure the status callback to write proactively to an external location such as AWS for post processing later. This helps prevent losing data points.

Twilio Functions have the same reliability as other Twilio platform capabilities. The following guide describes how to use functions to handle callbacks at scale: Handling High Volume Inbound SMS and Webhooks with Twilio Functions and Amazon SQS

Recommendations for maintaining messaging records

When sending a message request, record the relevant message details in persistent storage. Then, whether using Polling or Status Callbacks (we strongly recommend Status Callbacks), update messages with the status and associated Message SID once known. This persistent data store becomes the record of whether a message sent successfully or not.

If for some reason a message status hasn’t been updated to Delivered or Undelivered within 12 hours, it is possible that the status callback was not received. In this case, we recommend making a POLLING request to the Messaging API to retrieve the status of the message based on the Message SID.

It is always best practice to reconcile message statuses at least once a day to verify that no status events have been missed.

Additionally, as part of the reconciliation process Twilio can return a list of all messages SIDs for a given time frame. (See this blog post for details on Exporting SMS Logs in bulk.)

This list of SIDs can be used to determine if any messages got created during the SYNC phase for which no Message SID was returned. You can use the message envelope details like timestamp and recipient number to find the messages in your store that are missing these SIDs. (If you’re redacting data, the last 4 digits of the number may be removed, but the remaining digits may be enough to match the SIDs appropriately).

Additional Questions

Q: Can a user send a customer identifier for a message, or is only the Twilio-defined SID available?

A: Only the Twilio-defined SID is available.

It's also possible to subscribe to the Twilio debugger webhook and find out immediately when errors with your messages occur.

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.