SUPPORT.TWILIO.COM END OF LIFE NOTICE: This site, support.twilio.com, is scheduled to go End of Life on February 27, 2024. All Twilio Support content has been migrated to help.twilio.com, where you can continue to find helpful Support articles, API docs, and Twilio blog content, and escalate your issues to our Support team. We encourage you to update your bookmarks and begin using the new site today for all your Twilio Support needs.

Getting Started with Advanced Opt-Out for Messaging Services

Objective

By default, Twilio automatically handles a specific set of opt-in/opt-out related keywords, such as  STOP, START, and HELP. For more details on the default behavior, including the full list of reserved keywords and standard replies, see Twilio support for opt-out keywords (SMS STOP filtering).

If you wish to customize these keywords or the responses that users receive, you can use Advanced Opt-Out for Messaging Services. Advanced Opt-Out enables you to customize the keywords and responses for opt-out, opt-in and help messages to your numbers.

 

Product

Programmable Messaging

 

Procedure

How Advanced Opt-Out Works

The Advanced Opt-Out feature gives you the following options for each of your Messaging Services:

  • Add additional keywords for opt-out, opt-in and help messages
  • Customize your reply messages for keywords
  • Remove most of the default keywords (except for STOP, HELP, and START)
  • Add support for additional languages (e.g. keywords and replies in Spanish)
  • Add country-specific overrides, if needed (e.g. a unique set of keywords for Mexico mobile users)

Once your Advanced Opt-Out options are set, these customized opt-out settings will automatically be used in response to any keyword messages received to the short code and long code numbers associated with the Messaging Service.

Custom opt-out settings also apply to any WhatsApp senders in the Messaging Service. If a WhatsApp user texts one of those keywords, that user will be opted-out of further WhatsApp messaging from your Twilio WhatsApp sender and your Messaging Service. This opt-out currently will not generalize to SMS, so if you often send messages on multiple messaging channels to the same user, we recommend you remove that user from your contact list if they opt-out on one channel or the other.

Twilio will automatically handle replies to the keywords you've configured, but we will still let you know when you receive a message containing these keywords. If you have configured your Messaging Service to send incoming messages to a webhook, Twilio will POST the opt-out, help, or opt-in messages to your webhook to help you track these events. These will arrive with an extra parameter OptOutType, which will indicate whether the message is a STOP, HELP or START message. The incoming keyword messages will also appear in your SMS Logs in Twilio Console. Additionally, the OptOutType parameter is not included in the webhook payload unless you have Advanced Opt-Out enabled on the Messaging Service.

Please note, the replies you configure for Advanced Opt-Out will not appear in your Twilio SMS Logs. In addition, Advanced Opt-Out will still generate replies for configured keywords even if your Messaging Service is set to "Drop Incoming Messages." Twilio does not bill you for these outbound reply messages.

Notice: Advanced Opt-Out only changes the keyword handling for Twilio phone numbers in the Messaging Service on which it is configured. Twilio will continue automatically handling standard English-language replies for all opt-in/out keyword messages received on Toll-Free and Long Code phone numbers that are not a member of a Messaging Service. This default opt-out handling is not customizable. For more information on default opt-out responses, see Twilio support for opt-out keywords (SMS STOP filtering).

Notice: Twilio Toll-Free numbers only respond to START and UNSTOP for re-subscribe. Twilio cannot disable the STOP/UNSTOP replies for Toll Free Numbers. Even if Advanced Opt Out is enabled, end users will continue to receive the "Network MSG". Learn more here Opt-out keyword handling (SMS STOP Filtering) for Toll-Free SMS

 

Exceptions to Advanced Opt-Out Functionality for U.S/CA Toll-Free

We do not recommend using Advanced Opt-Out with Toll-Free numbers.

Toll-Free STOP/START messages are handled by the carrier outside Twilio. Your recipients will receive a standard "Network MSG" reply from the carrier regardless of your Advanced Opt-Out configuration. This behavior cannot be changed or removed at this time.

Learn more here: Opt-out keyword handling (SMS STOP Filtering) for Toll-Free SMS

 

Set Up Advanced Opt-Out

If you are not yet using a Messaging Service to send and receive messages, you will first need to set one up. You can create a Messaging Service in the Twilio Console and add your Twilio numbers to it. Read more about Messaging Services here.

Once you have a Messaging Service, Advanced Opt-Out can be configured from the Twilio Console:

  1. Access the Messaging Services page in Console.
  2. Click the desired Messaging Service
  3. Click the Opt-Out Management tab in the left-hand side bar.

From here, you can edit the default keywords and responses, add new keywords, add additional languages, and more. For a full tutorial on setting up Advanced Opt-Out, please see Configuring Advanced Opt-Out Keywords (Twilio Docs).

Please note that keyword responses have a maximum length of 320 characters. We recommend keeping your responses as concise as possible for the best user experience.

Notice: STOP, START, and HELP keywords can't be removed, as these are required for basic opt-out compliance. You can, however, remove all secondary keywords, such as CANCEL for opt-outs and YES for opt-in messages.

Notice: These custom replies should follow standard SMS rules and guidelines for content, and will travel through external carriers and mobile providers for delivery just like any other SMS message (though these are not visible in your actual Twilio messaging logs). This means that if you have to include a URL in the custom reply message, such as your website URL in the "HELP" response text, please make sure not to use a shared URL shortener like bit.ly, goo.gl, page.link, etc. as described in this guide. Carriers and providers may silently block or filter these replies if issues are detected there.

We also recommend testing your custom content by sending an SMS with a START, STOP, or HELP keyword from your own mobile device to one of the Twilio numbers in that Messaging Service, to ensure the proper response is received. If no auto-response message is received at all, try removing the URL from your custom content, then send another test to see if that was causing a block. While we generally advise against including any URLs in your custom response text, if absolutely necessary to include a link, and make sure to test the responses thoroughly.

 

How to Test your New Advanced Opt-Out Setup

You can test your new setup by adding a Twilio phone number to the Messaging Service the advanced opt-out has been enabled on (if not there already). Then send a message from your mobile device to this Twilio number with a "STOP" or "HELP" keyword. You should receive an auto-response to your device with the content you entered in the Advanced Opt-Out settings if everything is working.

For initial testing, please try a STOP or HELP keyword first. Sending a "START" keyword to your Twilio number without previously sending a "STOP" keyword will not trigger any action or auto-reply, as these opt-in keywords are only meant to be used to remove a previous opt-out or blocklist entry. 

 

Advanced Opt-Out API

There is currently no API access for managing Advanced Opt-Out configurations. There are also no options for exporting and/or importing configurations. At this time, Advanced Opt-Out is only configurable via Console.

Have more questions? Submit a request
We can’t wait to see what you build.
Powered by Zendesk