SMS Opt-Out Keywords

While opt-out keywords like STOP and UNSUBSCRIBE let people change their subscription preferences in Twilio, doesn’t receive SMS replies directly. But, you can create a webhook-triggered campaign to send unsubscribe information from Twilio to so you can reflect and respect your audience’s messaging preferences and privacy in

 Webhook triggers can do more than help with Twilio!

Webhook-triggered campaigns let you trigger campaigns when something happens in another system—not just Twilio! You can even relate data to people in one-to-many style operations. See our webhook-triggered campaign page to learn more about how you can take advantage of webhook-triggered campaigns

How it works

To handle opt-out keywords, we’ll create a webhook-triggered campaign. When someone sends an incoming message to your Twilio sender, Twilio will send a webhook to If the webhook payload contains an OptOutKeyword property, indicating that the customer wants to opt-out of messages, we’ll set the appropriate person’s sms_unsubscribe attribute to true.

flowchart LR a[Person sends
incoming SMS Message]-->b[Twilio sends webhook
to] b-->c subgraph z [ Campaign] c{Does webhook contain
opt out keyword?}-->|yes|d{does phone number match
someone in your audience?} d-->|yes|e[Set sms_unsubscribe
to true on person] c-.->|no|f[do nothing] d-.->|no|f end

Set up a campaign to handle opt-out keywords

This process requires Twilio’s Advanced Opt-Out feature. This feature lets you customize your response to inbound messages—like setting the sms_unsubscribe attribute on your audience in! If you haven’t already enabled this setting, we’ll tell you how as a part of this process.

  1. If you haven’t already, enable Twilio’s Advanced Opt-Out feature.

    1. In Twilio, go to the Messaging Services page and click your messaging service.
    2. Click Opt-Out Management, and then click Enable Advanced Opt-Out if the feature is disabled.

  2. In, go to Campaigns and click Create Campaign.

  3. Give your campaign a Name and Description.

    We’re going to create a campaign that only handles data and won’t send messages. You might give it a name like “SMS Opt-out” and enter a description explaining that this campaign is only handles data and assigns the sms_unsubscribe attribute.

    set the name and description for your campaign
    set the name and description for your campaign

  4. In the trigger step, click Data arrives via webhook and click Copy to copy the Webhook URL.

    set up your webhook trigger
    set up your webhook trigger

  5. In Twilio, go to Phone Numbers > Active numbers, scroll down to the Messaging section, and paste the URL you copied in the previous step under A MESSAGE COMES IN.

    Add your webhook to twilio
    Add your webhook to twilio

  6. (Optional, recommended) Using a test number, send an incoming message to your SMS sender number containing an opt out keyword. This simulated response populates a payload in that shows the information that Twilio forwards to us when you receive an incoming message. We’re going to use the OptOutType to populate our campaign.

    example twilio webhook data
    example twilio webhook data

  7. Go to the Workflow step of the campaign and add a True/False Branch to your workflow. Click the branch and give it a name; in our example, we’ve called it “Opted out”.

  8. Click Add condition. For the trigger attribute, type OptOutType and set the condition to exists. Click Save.

    set up your true/false condition
    set up your true/false condition

  9. Drag Batch Update into the True side of your branch. Despite it being a batch update, we’re only using this action to set the sms_unsubscribe attribute for the individual recipient of each message. Your workflow will look like this:

    Set a true/false branch to set attributes when the optouttype exists
    Set a true/false branch to set attributes when the optouttype exists

  10. Click the action and click Add Details.

  11. For Who do you want to update, click Add attribute condition and set the profile attributeA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. Attributes are analogous to traits in Data Pipelines. containing your audience’s phone number to the From value in the Trigger data.

  12. Under Which attributes do you want to add, change, or remove, set the sms_unsubscribe attribute to the Static value true.

    Send a batch update matching a person's phone to the from value in the webhook
    Send a batch update matching a person's phone to the from value in the webhook

  13. Save the batch update action, and then save and start your campaign.

Now, when people opt-out of SMS messages with an incoming opt-out keyword, we’ll reflect their opt out status appropriately in

Copied to clipboard!
Is this page helpful?