SMS Opt-Out Keywords
Twilio, like most SMS services, supports response keywords, letting people opt-out of Twilio SMS messages by replying with keywords like STOP
, QUIT
, etc.
While this conveniently lets people change their opt-in or -out preferences, Customer.io doesn’t receive these replies directly. We need to do a little bit of work to pass this information to Customer.io and set the sms_unsubscribe
attribute on people who reply to text messages with opt-out keywords to respect their preferences and privacy.
To handle opt-out keywords, we’ll create a service and function within Twilio that calls the Customer.io API to find people and set their sms_unsubscribe
attribute to true
. Then we’ll set up a Twilio workflow that calls this function when people send incoming SMS messages containing the keywords you specify. When you publish your Twilio Flow, anybody who sends an SMS message containing one of your keywords will automatically have their sms_unsubscribe
attribute set to true
in Customer.io.
Prerequisites
This process takes place almost entirely within Twilio. Before you begin, you’ll need:
- Your Track API credentials; our Twilio function uses the track API to set
sms_unsubscribed
attributes. - Your App API credentials; our Twilio function uses the App API to lookup people by incoming phone number.
- This script.
- A common text editor, to open and copy the contents of the script.
- An active Twilio phone number
Create new API credentials specifically for Twilio
We recommend that you have credentials specific to this integration, so you can manage credentials for Twilio without affecting other API consumers.
Set up your function
The opt-out flow will trigger a function that calls the Customer.io API. In Twilio, functions are contained by a service. So we need to create a service to house our function. The function itself is the script that you can find here.
Add dependencies to your Twilio Function
The script has two required NPM dependencies: axios
and axios-retry
. You can find the version requirements in the script comments, and Twilio’s documentation can help you add them to your function.
You’ll also have to set both Track API and App API credentials as environment variables in Twilio, so that your function can communicate with Customer.io. You can find credentials in your workspace settings.
To create your Customer.io keyword opt-out function:
Download the script above. You’ll need to copy the contents of this script into Twilio in later steps.
In Twilio, go to Functions under Runtime.
Click Services, click Create Service, and enter a name for your new service. Our examples use
customerio
. If you already have a service you want to add our opt-out function to, you can click that service instead.In the Functions editor, click Add and select Add Function.
Use a text editor to open the
twilio-opt-out/function.js
steps, and paste the contents of the file into the Twilio function editor. When you’re done, click Save.Click Environment Variables and add variables with your credentials. The keys and values are as follows:
API Key Value Format Track API TRACK_CREDS
<SITE ID>:<API KEY>
App API BEARER_TOKEN
API KEY
Click Deploy All.
Now you can reference your function in your opt-out flow.
Set up a Twilio opt-out Flow
As a part of this process, you’ll reference the function you set up above. If you haven’t set up your function, you should do that before you go through this process.
In Twilio, go to Studio > Manage Flows and click to add a new flow.
Drag a Split Based On… block into your workflow and connect it to the Incoming Message on your trigger.
Click your Split Based On… and set Variable To Test to message.Body.
On your Split Based On… block, click New and add conditions test the message body for your out-out keywords:
- You can use the Contains or Equal To conditions. When using Equal To, replies that contain any words or characters in addition to the opt-out keyword will not be unsubscribed (e.g. “Please Stop”, “Stop!").
- Set the value for each condition to the keyword you want to test. The common opt-out keywords for Twilio are STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, and QUIT. You must add individual conditions for each keyword.
- Click Save when you’ve added all of your conditions.
Drag Run Function into your workflow, and connect conditions from your Split Based On… block to the function.
Click the Run Function block and select the Service containing your opt-out function and the opt-out Function itself.
Add a Function Parameter for
from
with a value of{{trigger.message.From}}
Click Save. If you haven’t already set up a service and function, see the section above.
Click Publish.
Now you may want to test your implementation to make sure that the Twilio flow works. Incoming opt-out keywords should set the sms_unsubscribe
attribute to true
on the associated person in your workspaces. If multiple people in your workspace have the same phone number, your Twilio function will set sms_unsubscribe
to true
on all of them.


Associate the Twilio Flow with Messaging Replies
The last step of the process is to associate the Twilio opt-out Flow with Messaging Replies for the relevant phone number in your account.
- In your Twilio account, navigate to Phone Numbers, and then Active Numbers.
- Click the phone number that you would like to use for opt-out management.
- In the Messaging section of the phone number configuration, in the drop-down menu under When a message comes in, select Studio Flow in the left-hand drop-down menu, and in the right-hand drop-down menu select the name of the Flow you just created in the previous step.
- Click Save.
Now your Flow is set up to “listen” for incoming message replies.

