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:

1. Your Track API credentials; our Twilio function uses the track API to set sms_unsubscribed attributes.
2. Your App API credentials; our Twilio function uses the Beta API to lookup people by incoming phone number.
3. This script.
4. A common text editor, to open and copy the contents of the script.
5. An active Twilio phone number

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.

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:

1. Download the script above. You’ll need to copy the contents of this script into Twilio in later steps.

2. In Twilio, go to Functions under Runtime.

3. 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.

4. In the Functions editor, click Add and select Add Function.

5. 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.

   

   

6. 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

   

   

7. 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.

1. In Twilio, go to Studio > Manage Flows and click to add a new flow.

2. Drag a Split Based On… block into your workflow and connect it to the Incomming Message on your trigger.

3. Click your Split Based On… and set Variable To Test to message.Body.

4. On your Split Based On… block, click New and add conditions test the message body for your out-out keywords:

   • Use the Contains condition.
   • 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.

     

     

5. Drag Run Function into your workflow, and connect conditions from your Split Based On… block to the function.

6. Click the Run Function block and select the Service containing your opt-out function and the opt-out Function itself. Click Save. If you haven’t already set up a service and function, see the section above.

7. 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.

1. In your Twilio account, navigate to Phone Numbers, and then Active Numbers.
2. Click the phone number that you would like to use for opt-out management.
3. 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.
4. Click Save.

Now your Flow is set up to “listen” for incoming message replies.