In the realm of digital communication, managing user preferences is crucial for maintaining compliance and enhancing user experience. Twilio's Incoming Message Webhook and Event Streams features provide a mechanism to track opt-in, opt-out and Help messages using the OptOutType parameter. This article explores how to effectively utilize this parameter, highlighting the differences between these two methods.

Understanding the OptOutType Parameter

The OptOutType parameter is a key component in Twilio's Advanced Opt-Out and Event Streams  features, designed to help businesses track user engagement with opt-in, opt-out, and help keywords. This parameter is included in the webhook when Advanced Opt Out is enabled or event stream payload for any incoming messages that contain keywords like "STOP" or "START". 

A message will be recognised as an opt-in, opt-out or help message:

• Only when the full message body matches the keyword, eg. “Stop” will trigger an opt-out but “Stop please” will not
• Even if the message body is not case sensitive, e.g., "sToP" will be recognised as an opt-out message

The OptOutType will return either STOP, START or HELP depending on incoming messaging content. Read more below to understand the differences between using OptOutType in webhooks versus Event Streams. 

Tracking OptOutType Using Webhooks vs. Event Streams

Webhooks - Requires a Messaging Service with Advanced Opt Out

When a message containing an opt-out, opt-in or help keyword is received, Twilio sends a POST request to the configured incoming message webhook URL, including the OptOutType parameter only when the message is sent to a phone number within a Messaging Service that has Advanced Opt-Out enabled and is not configured to drop messages.

For more information on Advanced Opt Out, see here.

Configuration Requirements

1. Follow this guide in our product documentation to:
   1. Enable Advanced Opt Out on your Messaging Service
   2. Add your phone number to the Messaging Service Sender Pool
   3. Configure a webhook where you want to receive the payload information for incoming messages. The webhook can be configured either on the Messaging Service itself or on the individual phone number.

Event Streams - No need for Messaging Service with Advanced Opt Out

When a message containing an opt-out, opt-in or help keyword is received, Event Streams will send a JSON payload to your configured sink which can be a webhook, Segment or Amazon Kinesis instance. An Event Stream will be triggered for all incoming messages across all your numbers and Messaging Services. This means you do not need to have Advanced Opt Out configured, however if you do, the keywords configured on Advanced Opt Out will still send an OptOutType parameter to the Event Stream.

Configuration Requirements

1. See our Quick Start guides in our Event Streams documentation to set up your Event Stream sink
2. Follow the same quick start guide to subscribe to the com.twilio.messaging.inbound-message.received event type. See a list of other event types here
3. Choose your schema version. The OptOutType parameter is available from version 5 of the com.twilio.messaging.inbound-message.received event type

Frequently Asked Questions

Are messages that trigger OptOutType case sensitive?

No, OptOutType will be returned regardless of the case of the message, eg. “sTop” will trigger the OptOutType parameter to be returned.

Will OptOutType be returned if a keyword is part of a longer message, for example, “Stop, that’s so funny”

No, OptOutType will be returned only when the full message body is a keyword, eg. “Stop” will trigger an opt-out but “Stop, that’s so funny” will not.

Why do only some messages trigger the OptOutType parameter?

When using incoming message webhooks, only messages sent to phone numbers in Messaging Services that have Advanced Opt Out enabled and are not configured to drop messages will get an OptOutType parameter in the webhook. The webhook can be configured on either the Messaging Service or the phone number. Check if your number is part of the Messaging Service Sender Pool and that a webhook URL is configured.

If you need the OptOutType parameter on all messages, even if the recipient number is not in a Messaging Service with Advanced Opt Out, you can use Event Streams to get this information. See the article above for more information.

Why are we not getting OptOutType in the status callback?

The OptOutType parameter is available on incoming message webhooks and event streams, but not outgoing status callbacks. 

If the incoming webhook URL is configured on the phone number and not the Messaging Service, does the OptOutType parameter get triggered?

Yes it does, as long as the Messaging Service has Advanced Opt Out configured and the phone number is part of the Messaging Service Sender Pool.