Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

How to Optimize Message Deliverability with Message Feedback


In this guide you will learn when, why and how to send Message Feedback to report the outcome of whether the recipient of a message performed a specific tracked user action.

Message Feedback

  • Allows Twilio to optimize message deliverability.
  • Supports gathering of Messaging Insights on the conversion of One-Time Passwords (OTP) and similar tracked user actions performed by the message recipient.

Before you begin

before-you-begin page anchor

When should you use Message Feedback?

when-should-you-use-message-feedback page anchor

Message Feedback is intended for use cases where sending a message leads to a trackable user action performed by the message recipient. The primary use case is the sending of messages with one-time passwords (OTP) and similar authentication or account verification codes (PINs) in two-factor or multi-factor authentication (2FA or MFA) scenarios.

In these cases, there are consistently occurring trackable user actions which are uniquely identifiable, so they can be traced back to a specific sent Message and its Message Feedback subresource.

Examples of such trackable user actions include:

  • A user receives a message with a one-time verification code and enters it into a website or app for 2FA/MFA.
  • A user receives a message with a temporary password and uses it to reset the account password.
  • A user receives a message and replies to it with a call or message.
  • A user clicks on a unique link contained in the message.

Why should you send Message Feedback?

why-should-you-send-message-feedback page anchor

Sending messages nationally or internationally is not a one-size-fits-all operation. Message deliverability varies by geography, involved carriers, use case, and even for individual customers. Twilio uses a mix of automated algorithms and manual adjustments to ensure the best possible message deliverability for customers.

By providing Message Feedback you serve two related purposes:

Messaging Insights One-time Password (OTP) Conversion Report in Console.

How to submit Message Feedback

how-to-submit-message-feedback page anchor

Submitting Message Feedback to Twilio is a four-step process:

  1. Send a Message with ProvideFeedback enabled
  2. Store Message SID retrievable in response to the tracked user action
  3. Track the user action performed in response to Message receipt
  4. Send Message Feedback to confirm the tracked user action was performed
(information)

Info

As the use case details of your tracked user action may differ, the following step-by-step instructions focus on the correct usage of the Message resource and its Message Feedback subresource.

For illustration purposes, the following steps assume that

  • You send a message to the recipient (user) containing a URL with a unique confirmation id as a query parameter.
  • The tracked user action is the opening of the URL by the message recipient.
  • You implemented a means of retrieving the unique Message SID for a sent confirmation message on the basis of the confirmation id query parameter.

Step 1: Send a Message with ProvideFeedback enabled

step-1-send-a-message-with-providefeedback-enabled page anchor

Create a new Message with the ProvideFeedback parameter set to True to send the message underlying the uniquely trackable user action.

ProvideFeedback must be set to True at time of Message creation so that:

  • Twilio starts

    • Capturing the necessary data to track delivery performance from Message creation and sending to the expected confirmation that the tracked user action was performed.
    • Incorporating the gathered information in the Message Insights OTP Conversion Report immediately.
  • You can send Message Feedback in Step 4 to confirm the actual performance of the tracked user action.
(warning)

Warning

We recommend using the ProvideFeedback parameter only on OTP messages to ensure a clean set of OTP-related data in the OTP Conversion report.

Send the Message for which to provide Feedback

send-the-message-for-which-to-provide-feedback page anchor
Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.messages
_15
.create({
_15
body: 'Open to confirm: https://www.example.com/confirm?id=1234567890',
_15
from: '+15557122661',
_15
provideFeedback: true,
_15
to: '+15558675310'
_15
})
_15
.then(message => console.log(message.sid));

Output

_24
{
_24
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"api_version": "2010-04-01",
_24
"body": "Open to confirm: https://www.example.com/confirm?id=1234567890",
_24
"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",
_24
"direction": "outbound-api",
_24
"error_code": null,
_24
"error_message": null,
_24
"from": "+15557122661",
_24
"num_media": "0",
_24
"num_segments": "1",
_24
"price": null,
_24
"price_unit": null,
_24
"messaging_service_sid": "MGXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"sid": "SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_24
"status": "queued",
_24
"subresource_uris": {
_24
"media": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Media.json"
_24
},
_24
"to": "+15558675310",
_24
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Messages/SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_24
}


Step 2: Store Message SID retrievable in response to the tracked user action

step-2-store-message-sid-retrievable-in-response-to-the-tracked-user-action page anchor

Store the Message SID of the Message created in Step 1 such that you can retrieve it on the basis of the uniquely identifiable user action you are tracking.

For purposes of the illustrative scenario, the Message SID must be stored and retrievable on the basis of the unique id query parameter value contained in the URL sent with the Step 1 message.


Step 3: Track the user action performed in response to Message receipt

step-3-track-the-user-action-performed-in-response-to-message-receipt page anchor

Track the performance of the unique user action performed in response to the successful receipt of the Message sent in Step 1.

For purposes of the illustrative scenario, you know the tracked user action has been performed, when your backend route handler for the URL sent in Step 1 is called with the unique confirmation id as a query parameter.


Step 4: Send Message Feedback to confirm the tracked user action was performed

step-4-send-message-feedback-to-confirm-the-tracked-user-action-was-performed page anchor

Once you determine that the unique tracked user action in Step 3 has been performed by the message recipient, you

  • Retrieve the unique Message SID of the specific Message underlying the tracked user action.
  • Update the Message Feedback for the Message with Outcome parameter value confirmed to report to Twilio that the tracked user action was performed.
(information)

Info

Update the Message Feedback even if the Message is received with a delay once the conditions for confirmation are met. This ensures the Messaging Insights are current and message delivery optimizations are based on complete information.

Do not update the Message Feedback if the tracked user action is not performed, this will result in the Message Feedback resource's outcome status correctly remaining unconfirmed.

Send Message Feedback to confirm performance of the tracked user action

send-message-feedback-to-confirm-performance-of-the-tracked-user-action page anchor
Node.js
Python
C#
Java
PHP
Ruby
curl

_40
// Twilio Credentials
_40
// To set up environmental variables, see http://twil.io/secure
_40
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_40
const authToken = process.env.TWILIO_AUTH_TOKEN;
_40
_40
// require the Twilio module and create a REST client
_40
const client = require('twilio')(accountSid, authToken);
_40
_40
const http = require('http');
_40
const express = require('express');
_40
_40
const app = express();
_40
_40
app.get('/confirm', (req, res) => {
_40
const uniqueId = req.query.id;
_40
_40
// Lookup constiable `uniqueId` in a database to find messageSid
_40
const messageSid = 'SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';
_40
_40
// Send Feedback to Twilio
_40
client
_40
.messages(messageSid)
_40
.feedback.create({
_40
outcome: 'confirmed',
_40
})
_40
.then(() => {
_40
// Handle remaining request normally
_40
res.send('Thank you!');
_40
res.end();
_40
})
_40
.catch(err => {
_40
res.status(500);
_40
res.send(err.toString());
_40
})
_40
.done();
_40
});
_40
_40
http.createServer(app).listen(1337, () => {
_40
console.log('Express server listening on port 1337');
_40
});

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"message_sid": "SM6d4d807e10f24d83a1ab01da10ccc0f5",
_10
"outcome": "confirmed",
_10
"date_created": "Fri, 02 Sep 2016 18:19:59 +0000",
_10
"date_updated": "Fri, 02 Sep 2016 18:42:40 +0000",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM6d4d807e10f24d83a1ab01da10ccc0f5/Feedback.json"
_10
}


Now that you have learned why, when and how to provide Message Feedback, you may wish to check out the following:


Rate this page: