Compliance: Tracking and Managing Opt-Outs (STOP/START Keywords)

Depending on your setup, opt-outs may be handled automatically by your SMS gateway (for example, Twilio) or tracked manually using flows, groups, and contact fields.

When using a Twilio SMS channel, opt-outs are handled automatically at the provider level.

Twilio will automatically unsubscribe a contact when they send any of the following keywords:

• STOP
• STOPALL
• UNSUBSCRIBE
• CANCEL
• END
• QUIT

Once unsubscribed:

• The contact will no longer receive messages from that number
• The contact remains in any active flow until the flow expires

[CAPTURE: Example SMS conversation where a contact sends STOP and receives Twilio’s automatic opt-out confirmation message.]

Important: You cannot override Twilio’s opt-out behavior. Messages sent to an unsubscribed contact will fail until they opt back in.

If a contact wants to opt back in, they must send:

• START or YES

Twilio also supports:

• HELP and INFO, which return a stock message explaining available commands

Note: Opt-out and opt-in keywords apply at the provider level for the Twilio number the contact is messaging.

You can manually view opt-outs directly from your Twilio channel settings by reviewing logs and error details.

Open the Twilio channel log

1. Navigate to Settings
2. Click your Twilio phone number
3. In the Errors panel, click View Log

[CAPTURE: Twilio channel settings page with the Errors panel and View Log option visible.]

Identify blacklist / opt-out blocking

In the log, you may see an error similar to:

• HTTP 400 error: 21610 – The message From/To pair violates a blacklist rule

This error means:

• The contact previously sent an opt-out keyword
• Twilio blocked the message
• You were not charged for the failed attempt

[CAPTURE: Twilio error log displaying error 21610 for a blocked message.]

Important: To send messages again, the contact must text START or YES to opt back in.

In addition to Twilio’s automatic handling, you can track opt-outs inside RapidPro for reporting and automation.

Option 1: Use an “Unsubscribed” group

• Create a group named Unsubscribed
• Add contacts to this group when they opt out

Option 2: Use a flow with opt-out keywords

Create a flow that:

• Uses keyword triggers matching: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT
• Adds the contact to your Unsubscribed group

[CAPTURE: Flow with keyword triggers leading to an Add contact to a group action for the Unsubscribed group.]

Option 3: Use a contact field

Create a contact field such as Unsubscribed and update it in the opt-out flow.

Example behavior:

• When a contact sends an opt-out keyword, the Unsubscribed field is set to Yes

[CAPTURE: Update the contact action setting a field named Unsubscribed to Yes.]

Option 4: Notify your team

You can also notify your team when an opt-out occurs:

• Send an SMS using Send a message to somebody else
• Send an email using Send an email

Summary: Once configured, you can track opt-outs by viewing contacts in the Unsubscribed group, checking a contact’s Unsubscribed field, or receiving SMS/email notifications.

You can also update a contact’s status within a flow:

• Active
• Stopped
• Blocked

Important: Blocked contacts will not receive messages, regardless of group membership.

For more details, see Updating a Contact’s Status in a Flow.

Contacts may not know how to opt out or opt back in unless you tell them.

Best practices include:

• Explaining opt-out keywords during registration
• Including opt-out information in welcome messages
• Following up by email (if available) after a contact unsubscribes

Tip: Let contacts know they can re-subscribe by texting START or YES.