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
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:
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:
Submitting Message Feedback to Twilio is a four-step process:
ProvideFeedback
enabled
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
id
as a query parameter.
id
query parameter.
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
We recommend using the ProvideFeedback
parameter only on OTP messages to ensure a clean set of OTP-related data in the OTP Conversion report.
1// Download the helper library from https://www.twilio.com/docs/node/install2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";34// Find your Account SID and Auth Token at twilio.com/console5// and set the environment variables. See http://twil.io/secure6const accountSid = process.env.TWILIO_ACCOUNT_SID;7const authToken = process.env.TWILIO_AUTH_TOKEN;8const client = twilio(accountSid, authToken);910async function createMessage() {11const message = await client.messages.create({12body: "Open to confirm: https://www.example.com/confirm?id=1234567890",13from: "+15557122661",14provideFeedback: true,15to: "+15558675310",16});1718console.log(message.body);19}2021createMessage();
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"api_version": "2010-04-01",4"body": "Open to confirm: https://www.example.com/confirm?id=1234567890",5"date_created": "Thu, 24 Aug 2023 05:01:45 +0000",6"date_sent": "Thu, 24 Aug 2023 05:01:45 +0000",7"date_updated": "Thu, 24 Aug 2023 05:01:45 +0000",8"direction": "outbound-api",9"error_code": null,10"error_message": null,11"from": "+15557122661",12"num_media": "0",13"num_segments": "1",14"price": null,15"price_unit": null,16"messaging_service_sid": "MGaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",17"sid": "SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",18"status": "queued",19"subresource_uris": {20"media": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Media.json"21},22"tags": {23"campaign_name": "Spring Sale 2022",24"message_type": "cart_abandoned"25},26"to": "+15558675310",27"uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Messages/SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"28}
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.
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.
Once you determine that the unique tracked user action in Step 3 has been performed by the message recipient, you
Outcome
parameter value
confirmed
to report to Twilio that the tracked user action was performed.
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
.
1// Twilio Credentials2// To set up environmental variables, see http://twil.io/secure3const accountSid = process.env.TWILIO_ACCOUNT_SID;4const authToken = process.env.TWILIO_AUTH_TOKEN;56// require the Twilio module and create a REST client7const client = require('twilio')(accountSid, authToken);89const http = require('http');10const express = require('express');1112const app = express();1314app.get('/confirm', (req, res) => {15const uniqueId = req.query.id;1617// Lookup constiable `uniqueId` in a database to find messageSid18const messageSid = 'SMXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX';1920// Send Feedback to Twilio21client22.messages(messageSid)23.feedback.create({24outcome: 'confirmed',25})26.then(() => {27// Handle remaining request normally28res.send('Thank you!');29res.end();30})31.catch(err => {32res.status(500);33res.send(err.toString());34})35.done();36});3738http.createServer(app).listen(1337, () => {39console.log('Express server listening on port 1337');40});
1{2"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",3"message_sid": "SM6d4d807e10f24d83a1ab01da10ccc0f5",4"outcome": "confirmed",5"date_created": "Fri, 02 Sep 2016 18:19:59 +0000",6"date_updated": "Fri, 02 Sep 2016 18:42:40 +0000",7"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/SMS/Messages/SM6d4d807e10f24d83a1ab01da10ccc0f5/Feedback.json"8}
Now that you have learned why, when and how to provide Message Feedback, you may wish to check out the following: