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
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.
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
- 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.
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.
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.
Click Environment Variables and add variables with your credentials. The keys and values are as follows:
API Key Value Format Track API
<SITE ID>:<API KEY>
Click Deploy All.
Now you can reference your function in your 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
fromwith a value of
Click Save. If you haven’t already set up a service and function, see the section above.
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
true on all of them.
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.