Menu

Expand
Rate this page:

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
RAW BODY
SmsSid=SM4262411b90e5464b98a4f66a49c57a97&SmsStatus=sent&MessageStatus=sent&To=%2B15622089096&MessagingServiceSid=MG4d9d720b38f7892254869fabdca51e69&MessageSid=SM4262411b90e5464b98a4f66a49c57a97&AccountSid=AC0db966d80e9f1662da09c61287f8bba1&From=%2B16232320112&ApiVersion=2010-04-01

Example Callback for Queued

MessageStatus: queued
MessageSid: SM4262411b90e5464b98a4f66a49c57a97
MessagingServiceSid: MG4d9d720b38f7892254869fabdca51e69
AccountSid: AC0db966d80e9f1662da09c61287f8bba1
From: +16232320112
ApiVersion: 2010-04-01
To: +15622089096
SmsStatus: queued
SmsSid: SM4262411b90e5464b98a4f66a49c57a97
RAW BODY
SmsSid=SM4262411b90e5464b98a4f66a49c57a97&SmsStatus=queued&MessageStatus=queued&To=%2B15622089096&MessagingServiceSid=MG4d9d720b38f7892254869fabdca51e69&MessageSid=SM4262411b90e5464b98a4f66a49c57a97&AccountSid=AC0db966d80e9f1662da09c61287f8bba1&From=%2B16232320112&ApiVersion=2010-04-01

Example Callback for Delivered

MessageStatus: delivered
MessageSid: SM4262411b90e5464b98a4f66a49c57a97
MessagingServiceSid: MG4d9d720b38f7892254869fabdca51e69
AccountSid: AC0db966d80e9f1662da09c61287f8bba1
From: +16232320112
ApiVersion: 2010-04-01
To: +15622089096
SmsStatus: delivered
SmsSid: SM4262411b90e5464b98a4f66a49c57a97
RAW BODY
SmsSid=SM4262411b90e5464b98a4f66a49c57a97&SmsStatus=delivered&MessageStatus=delivered&To=%2B15622089096&MessagingServiceSid=MG4d9d720b38f7892254869fabdca51e69&MessageSid=SM4262411b90e5464b98a4f66a49c57a97&AccountSid=AC0db966d80e9f1662da09c61287f8bba1&From=%2B16232320112&ApiVersion=2010-04-01

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 will be populated by default, however for reporting purposes you may add additional identifiers as URL query parameters if setting your status callback programmatically.

For debugging purposes, it is also possible to subscribe to the Twilio debugger webhook and find out immediately when errors with your messages occur.

References & Additional Tools

  1. Exporting SMS and Call Logs
  2. Messaging List Resource
  3. Handling High Volume Inbound SMS and Webhooks with Twilio Functions and Amazon SQS
  4. Twilio debugger webhook
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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more