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 or outbound messaging, but the process is similar for inbound messaging using Twilio-supported Messaging Channels, but the process is similar for inbound messaging.
When you first make a request to the Programmable Messaging API, Twilio responds synchronously with either a 200 (success) or a 400 (failure) HTTP status code. If the request was successful, Twilio returns the Message SID in the response.
The Message SID is your record that an outbound message was created. Twilio recommends that you store this Message SID along with the initial status of the message at the time Twilio returned the Message SID to you.
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"api_version": "2010-04-01",4"body": "Join Earth's mightiest heroes. Like Kevin Bacon.",5"date_created": "Thu, 30 Jul 2015 20:12:31 +0000",6"date_sent": "Thu, 30 Jul 2015 20:12:33 +0000",7"date_updated": "Thu, 30 Jul 2015 20:12:33 +0000",8"direction": "outbound-api",9"error_code": null,10"error_message": null,11"from": "+15017122661",12"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",13"num_media": "0",14"num_segments": "1",15"price": null,16"price_unit": null,17"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",18"status": "sent",19"subresource_uris": {20"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"21},22"to": "+15558675310",23"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"24}
Your outbound message changes status throughout its lifecycle - from creation, through sending, to delivery, and even read receipt for supporting messaging channels.
See the complete list of Message Status values for an explanation of each status.
There are two ways for a user to receive message status updates:
At any point after a successful message creation, you can make a GET request to the Programmable Messaging API using the Message SID to determine the status of the message. Twilio returns the message record including the message status.
See Fetch a Message Resource for request details and a sample response which includes the message status. This works fine for small-volume use cases and ad hoc analysis but for large-scale logging, you should use status callbacks.
Twilio status callbacks allow you to track message status changes for outbound messages.
Outbound Message Status in Status Callbacks provides details on the expected transitions between message status values and for which status changes Twilio sends status callbacks.
You can follow our guide on tracking the message status of outbound messages for a foundational understanding of how to use these status callbacks.
1MessageStatus: delivered2MessageSid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX3MessagingServiceSid: MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX4AccountSid: ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX5From: +162323201126ApiVersion: 2010-04-017To: +156220890968SmsStatus: delivered9SmsSid: SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
The Programmable Messaging API's raw response may appear different from the above example.
For customers sending millions of messages in a given day, handling a high volume of callbacks can present an operational risk. Imagine sending 10 million messages and receiving 20 million callbacks. Using Twilio Functions, you can configure your status callback endpoint to write proactively to an external location such as AWS for post processing later.
Twilio Functions have the same reliability as other Twilio platform capabilities. For using Twilio Functions at scale, see Twilio Serverless Status Callback Handler built in AWS
Record the relevant message details in persistent storage.
Update messages with the status and associated Message SID once known (whether you're using polling or status callbacks. Twilio recommends using Status Callbacks). This persistent data store becomes the record of whether a message was sent successfully or not.
If a message status hasn't been updated to delivered or undelivered within 12 hours, make a polling request to the Programmable Messaging API to retrieve the status of the message based on the Message SID. It is possible that the status callback was not received.
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 Support article 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 the message timestamp and recipient phone number (To) to find matching messages in your store that are missing these SIDs. If you're redacting data, the last 4 digits of the recipient phone number may be removed, but the remaining digits may be enough to match the SIDs appropriately.
While a message returns the Twilio-defined SID by default, you may add more identifiers as URL query parameters when setting your status callback programmatically.
For debugging purposes, you can also subscribe to the Twilio debugger webhook and get notified immediately when errors with your messages occur.