Message Feedback

Message Feedback API Overview

Sending text messages around the world is not a one-size-fits-all operation. Deliverability varies by geography, mobile operator, use case, and even for individual companies. There are many different knobs that Twilio can tune, such as different routing paths and carrier configurations. Twilio’s backend uses a mix of automated algorithms and manual adjustments to ensure the best possible deliverability for our customers. We tweak these parameters regularly to keep up with the ever changing telecom ecosystem. We have several sources of data we use to make sure that the configuration changes we are making are improving deliverability, but we trust what you tell us the most. 

The Message Feedback API enables customers to report back to Twilio in real-time when a text message is successfully delivered. By using this feedback information, Twilio can then detect and quickly react to changes in the global messaging networks, both in aggregate and specific to your account, thereby improving the delivery of your messages. It is one of the best tools at our disposal to understand your message deliverability and enable us to automatically optimize it on your behalf.

The feedback information you report can also be view in your Console so you can monitor and understand your message deliverability. Feedback information is aggregated every 15 minutes and will only display once you have reported feedback information to Twilio.

The Message Feedback API is useful to Twilio customers who have some trackable user action that results from their message being sent. Examples of trackable user actions include:

  • A user receives a passcode via SMS and enters it into a web site or app
  • A user enters a temporary password
  • A user replies to a message with a call or SMS
  • A user clicks on a unique link contained in the message

Once a user takes a trackable action, you can guarantee they received the message. Simply submit this information to Twilio, and we take care of the rest.

How to use this API

Submitting Message Feedback to Twilio is a three step process:

  1. When you send a message, let Twilio know that you are expecting a trackable user action by including the ProvideFeedback=true parameter in the initial HTTP POST.
  2. Save the Message SID from the POST response. You'll need this later.
  3. When the user takes the expected action, let Twilio know by sending a POST request to the Message Feedback instance subresource with Outcome=confirmed parameter. If the user does not take an action, do not POST anything.

Feedback is a subresource of a Messages instance resource. It represents the user-reported outcome of a message.

Resource URI 

/2010-04-01/Accounts/{AccountSid}/Messages/{MessageSid}/Feedback

Resource Properties

A Message Feedback instance resource is represented by the following properties:

Property Description
Outcome unconfirmed or confirmed. If ProvideFeedback=true in the initial HTTP POST, this value will default to unconfirmed. Make an HTTP POST to update this value to confirmed after the message arrives.

Outcome Values

The following are the possible values for the Outcome parameter:

Outcome Description
unconfirmed The message has not yet arrived at the To phone number. Note that this may mean the message has failed or it is still pending. For the purposes of the Message Feedback API, these two states are considered the same. Your application should not POST this value as it will be automatically set when the initial HTTP POST includes ProvideFeedback=true.
confirmed The message has arrived at the To phone number. Even if the message is delayed in delivery, you should still POST this value as soon as you have confirmed that the message was received.

HTTP GET

Not supported

HTTP POST

If the message was originally sent with ProvideFeedback=true, the Outcome of the Message Feedback instance will be unconfirmed by default. As soon as the message is confirmed as having arrived at the device, use an HTTP POST to the Message Feedback instance resource to update the Outcome to confirmed.

HTTP PUT

Not supported

HTTP DELETE

Not supported

Helper Library Support

The Message Feedback endpoint is supported in our Next Generation Helper Libraries, but not in our legacy helper libraries.

If you are not already using the Next Generation Helper Libraries, you can still use the Message Feedback API by POSTing directly to the REST endpoint.

Example Usage

Set the ProvideFeedback parameter to 'true' when you send the message.

curl -X POST 'https://api.twilio.com/2010-04-01/Accounts/ACa9b8c7d6e5f43120a9b8c7d6e5f43120/Messages.json' \
--data-urlencode 'To=+18085551234'  \
--data-urlencode 'From=+16045559876'  \
--data-urlencode 'Body=Your verification code is: 249205' \
--data-urlencode 'ProvideFeedback=true'  \
-u ACa9b8c7d6e5f43120a9b8c7d6e5f43120:[AuthToken]

Save the message SID which is included in the response.

{"sid": "SM1f2e3d4c5b6a70891f2e3d4c5b6a7089", "date_created": "Thu, 14 Jul 2016 14:18:40 +0000", ...}

If the user receives the text message, make an additional POST to the Feedback subresource to set the Outcome to 'confirmed'

curl -X POST 'https://api.twilio.com/2010-04-01/Accounts/ACa9b8c7d6e5f43120a9b8c7d6e5f43120/Messages/SM1f2e3d4c5b6a70891f2e3d4c5b6a7089/Feedback.json' \
--data-urlencode 'Outcome=confirmed'  \
-u ACa9b8c7d6e5f43120a9b8c7d6e5f43120:[AuthToken]

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.