Skip to main content

Documentation Index

Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt

Use this file to discover all available pages before exploring further.

Managing opt-outs correctly keeps your program compliant and protects subscribers who want to stop receiving messages. How you handle opt-outs depends on your sender type: whether it can receive inbound replies or not.

​
Opt-out keywords

STOP, HELP, and START are the canonical carrier-mandated compliance keywords. Their default replies are protected and cannot be changed via the OneSignal dashboard or API:
  • STOP opts the user out of SMS messages from a specific sender. Recognized aliases (UNSUBSCRIBE, CANCEL) share the same protected reply.
  • HELP returns information about your messaging program.
  • START lets the user opt back in after opting out. Recognized aliases (UNSTOP, YES) share the same protected reply.
To customize a default reply, contact support@onesignal.com with your App ID and the new response message. By default, when a user texts STOP, OneSignal replies: “You have successfully been unsubscribed. You will not receive any more messages from this number. Reply START to resubscribe.”
By default, an opt-out only prevents messages from the specific sender the subscriber texted. This ensures opt-outs are scoped to the use case. A subscriber who texts STOP to your promotional sender continues to receive transactional messages and OTPs from your other senders.

​
Managing opt-outs for alphanumeric senders

Alphanumeric sender IDs (e.g., “ACME” instead of a phone number) cannot receive inbound replies, which means subscribers can’t text STOP to opt out. To stay compliant, you must provide a web-based unsubscribe page that processes the opt-out and updates the subscriber’s status in OneSignal via the API.
1

Include an unsubscribe link in every message

Add a URL to a hosted unsubscribe page in each SMS you send. Use OneSignal Liquid tags to identify the subscriber in the URL:
To opt out: https://yourbrand.com/sms-unsubscribe?uid={{ onesignal_id }}
OneSignal renders {{ onesignal_id }} (or {{ subscription_id }}) into the subscriber’s actual ID at send time, so each recipient gets a personalized unsubscribe link.
2

Build the unsubscribe page

Host a simple web page at that URL. When the page loads, it reads the subscriber ID from the query parameter. The page should:
  • Confirm to the subscriber what they’re opting out of (e.g., “You will no longer receive promotional text messages from ACME.”)
  • Display a confirmation button. Don’t auto-unsubscribe on page load, since accidental clicks and link previews could trigger unintended opt-outs.
  • Optionally let the subscriber choose which message types to opt out of, if you send multiple types from the same sender.
3

Call the OneSignal API to process the opt-out

When the subscriber confirms, call the OneSignal API to update their subscription status. Two options depending on the scope:
  • Full unsubscribe from the sender: Use the Update Subscription API to set the subscription’s status to unsubscribed.
  • Opt out of a specific message type: Use the Edit Tags API to set a tag (e.g., promo = false), then exclude subscribers with that tag when sending that message type.
4

Show a confirmation

After the API call succeeds, display a confirmation message (e.g., “You’ve been unsubscribed. You will no longer receive promotional texts from ACME.”).

SMS opt-in and collection

Collect valid consent before sending SMS, so subscribers reach this opt-out flow only after opting in.

​
Managing opt-outs for shared senders

We don’t recommend sharing senders across text programs (promotional, transactional, or OTP). When a subscriber texts STOP, they are unsubscribed from the entire sender, meaning opting out of promotional messages would also block transactional messages like order confirmations or account alerts. Use separate senders for each use case whenever possible.
If you do have a shared sender, you can use custom keywords to let subscribers opt out of specific message types without unsubscribing from everything. This works by tagging subscribers when they text an opt-out keyword, then excluding those subscribers when sending that type of message. How it works:
  1. A subscriber texts a custom opt-out keyword to your sender (e.g., NOPROMO).
  2. OneSignal applies a data tag to that subscriber’s profile (e.g., promo = false).
  3. When you send a promotional campaign, you filter your audience to exclude subscribers where promo = false.
Setting up custom opt-out keywords: Go to Settings > Platforms > SMS Settings > Keywords and create a keyword for each use case you want subscribers to be able to opt out of independently. Example: promotional opt-out keyword (NOPROMO):
  1. Enter the keyword text (e.g., NOPROMO).
  2. Set audience scope to Anyone.
  3. Select or create a reply template (e.g., “You’ve been unsubscribed from promotional messages. You’ll still receive order and account notifications. Text STOP to unsubscribe from all messages.”).
  4. Assign a data tag: promo = false.
Repeat for each use case. For transactional messages, create NOTRANSACT with transactional = false. Excluding opted-out subscribers at send time: When building a campaign or Journey for a specific use case, use the User Tag filter in Segments to exclude subscribers who have opted out. For example, when sending a promotional message, exclude subscribers where promo = false. Important limitations:
  • Default compliance keywords (STOP, HELP, START) still apply to the entire sender and cannot be scoped to a use case.
  • You must include the custom opt-out keyword in every message of that type (e.g., “Reply NOPROMO to stop promotional texts”).
  • Alphanumeric sender IDs cannot receive replies and do not support keywords.
  • Reply syncing must be enabled. Go to Settings > Platforms > SMS Settings > Senders > Setup Replies.

SMS keywords

Full reference for setting up custom keywords, including two-way campaigns and preference centers.

​
Resubscribing

Once a user has opted out using a default opt-out keyword, they cannot be resubscribed through the OneSignal dashboard or API. The user must text a resubscribe keyword (START, UNSTOP, or YES) to the same sender number.

​
HELP keyword

By default, when a user texts HELP, OneSignal replies: “Reply STOP to unsubscribe. Msg&Data Rates May Apply.”

​
Auto-responder

Set an auto-reply for any incoming message that doesn’t match a keyword. Use this to redirect users to customer support, collect their intent, or notify your team for follow-up.
1

Go to Auto-Responder settings

Navigate to Settings > Platforms > SMS Settings > Auto-Responder.
2

Add an auto-responder

Click Add Auto-Responder and select a reply template.
3

Optionally tag the user

Assign a data tag when the auto-responder fires to enable future segmentation or alerting.

​
Viewing a subscriber’s opt-out status

To see which senders a subscriber is opted out of:
  1. Go to Audience > Subscriptions in the OneSignal dashboard.
  2. Search for the subscriber by External ID, email, or phone number.
  3. Open their SMS subscription and look under Consent by Sender.
This section shows the opt-in or opt-out status for each sender associated with that subscription.

​
FAQ

​
What happens when a user texts STOP to a shared sender?

They are opted out of all messages from that sender, including transactional messages and OTPs. This is why we strongly recommend using separate senders for each program type. Once opted out via STOP, the user must text START (or another resubscribe keyword) to the same sender to receive messages again.

​
Can I change the STOP or HELP response messages?

Yes, but not via the dashboard or API. Contact support@onesignal.com with your App ID and the new response text.

​
What opt-out mechanism do I use for alphanumeric sender IDs?

Alphanumeric sender IDs cannot receive replies, so you must include an unsubscribe link in every message and build a web-based unsubscribe page that calls the OneSignal API to process the opt-out. See the Managing opt-outs for alphanumeric senders section above.

​
Can I re-subscribe a user who texted STOP?

You cannot re-subscribe a user through the dashboard or API. The user must text START, UNSTOP, or YES to the same sender number to opt back in.

​
How do I prevent a single STOP from blocking all message types?

Use separate senders for each program type (promotional, transactional, OTP). If you must use a shared sender, set up custom opt-out keywords (e.g., NOPROMO) and exclude opted-out subscribers by tag at send time. Note that the default STOP keyword still unsubscribes from the entire sender.