Opt-Ins and Opt-Outs

What are opt-ins and opt-outs?

• Opt-out: a recipient who chooses not to receive further messages. We stop sending them additional messages.

• Opt-in: a recipient who previously opted out and wants to start receiving messages again, or who has no recorded opt-out at all.

We treat recipients as eligible to receive messages unless we have an opt-out on record for them. You're still responsible for getting any consent the law requires before messaging someone.

Sending to opted-out recipients

If you send to a recipient who's opted out, the message fails with error code 1002: RecipientOptedOut. It won't be delivered, and you can use this code to detect and handle opted-out recipients in your integration.

Opt-in and opt-out settings

These settings define the keywords and auto-reply messages used for opt-in, opt-out, and help on a Messaging Config. They can use custom values you set on the Messaging Config, or values synced from the linked TCR campaign.

The following keywords are always active. You don't need to configure them, and you can't disable or reassign them:

Keyword matching is case-insensitive, so stop, Stop, and STOP all trigger the opt-out workflow.

Default auto-reply messages

We send these when you haven't configured a custom message, or when TCR settings don't provide one for the matching action:

How opt-in and opt-out settings work

You manage these on a Messaging Config: either configure values directly there, or sync available values from the linked TCR campaign.

Use custom Messaging Config settings

When UseTCRSettings is off, your Messaging Config is the source of truth for custom behavior. Standard keywords stay active, and any custom keywords or messages you've set are layered on top.

For example, if your Messaging Config adds CONTINUE and RESUME as custom opt-in keywords, the effective opt-in keyword list becomes: START, UNSTOP, CONTINUE, RESUME.

Use TCR campaign settings

When UseTCRSettings is on, we use opt-in, opt-out, and help values from the linked TCR campaign wherever they're available. Standard keywords stay active, and we fall back to default messages when the TCR campaign doesn't provide one.

For example, if the linked TCR campaign defines STOP and OPTOUT as opt-out keywords, the effective opt-out keyword list becomes: STOP, QUIT, END, UNSUBSCRIBE, OPTOUT.

How recipients opt in, opt out, or request help

Single vs. double opt-outs

When a recipient opts out, they stop receiving messages either from one sender phone number, or from that phone number and its associated TCR campaign.

• Single opt-out: the sender's phone number isn't associated with a TCR campaign, or is toll-free. The recipient opts out from that phone number only.

• Double opt-out: the sender's phone number is associated with a TCR campaign. The recipient opts out from both that phone number and the TCR campaign, which applies to every sender phone number tied to that campaign.

Webhooks for opt-in and opt-out events

Opt-in and opt-out webhooks are Messaging Config webhooks (see the Webhooks article). For a given phone number, we send them according to whichever Messaging Config is currently attached to that number.

Single opt-in and opt-out

One webhook is sent:

{
  "ScopeType": "SenderPhoneNumber",
  "Scope": "+11234567890"
}

Double opt-in and opt-out

Two webhooks are sent. Phone number-level scope:

{
  "ScopeType": "SenderPhoneNumber",
  "Scope": "+11234567890"
}

TCR campaign-level scope:

{
  "ScopeType": "TcrCampaign",
  "Scope": "C123456"
}

For full payload examples, see Webhook Samples.

Migrating opt-outs from another provider

If you're migrating from another provider, you can import your existing opt-outs. See the Opt-Outs API documentation for details.

Feature availability

Opt-in and opt-out handling is on by default. Our support team can disable it for your account on request. This is separate from the per-Messaging Config keyword and message settings above: it's an on/off switch for the entire workflow rather than a way to adjust individual keywords.