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, doesn’t receive these replies directly. We need to do a little bit of work to pass this information to 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 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


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

 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 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 You can find credentials in your workspace settings.

To create your 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.

    Copy the script into the function box
    Copy the script into the function box

  6. Click Environment Variables and add variables with your credentials. The keys and values are as follows:

    APIKeyValue Format
    Environment variables for API credentials
    Environment variables for API credentials
  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 Incoming 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:

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

  7. Add a Function Parameter for from with a value of {{trigger.message.From}}

  8. Click Save. If you haven’t already set up a service and function, see the section above.

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

A complete Twilio flow to handle keyword-based opt-outs
A complete Twilio flow to handle keyword-based opt-outs

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.

Copied to clipboard!
Is this page helpful?