SMS keywords

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.

SMS keywords let subscribers text a specific word or phrase to your sender and receive an automated reply. You can use keywords for two things: two-way engagement campaigns (polls, content unlocks, preference collection) and preference centers (letting subscribers manage which types of messages they receive).

---

​

Two-way keyword campaigns

SMS campaigns don’t have to be one-directional. You can run keyword-based campaigns where subscribers reply to interact, including polls, surveys, preference collection, and content unlocks. Include a CTA in your message asking subscribers to reply with a keyword (e.g., “Reply EA for early access”). When OneSignal receives a message that matches the keyword, it triggers an automated reply and optionally applies a data tag to the subscriber’s profile.

​

Setting up a keyword

​

Measuring keyword engagement

To track how many times a keyword is triggered:

1. Go to Templates.
2. Check the analytics for the template tied to your keyword reply.

For example, if the early_access template shows 300 sends, the EA keyword was triggered 300 times. For this count to equal keyword triggers, use a dedicated reply template per keyword. If the template is reused by another keyword or campaign, the send count includes those uses too.

​

Building a segment from keyword engagement

Create targeted campaigns based on users who responded with specific keywords:

1. Go to Segments.
2. Use the User Tag filter.
3. Enter the tag you assigned when setting up the keyword (e.g., early_access = true).
4. Save and use this segment in your campaigns and Journeys.

---

​

Preference centers

A preference center lets subscribers self-select the types of messages they want to receive. Rather than a single all-or-nothing opt-out, subscribers can opt in or out of specific lists, such as seasonal promotions, product categories, restock alerts, and VIP offers, by texting a keyword. OneSignal tracks these preferences as data tags on each subscriber’s profile.

​

How it works

1. A subscriber texts a keyword to your sender (e.g., FALL).
2. OneSignal applies a data tag to that subscriber’s profile (e.g., fall = true).
3. When you send a campaign, you filter your audience to subscribers who have that tag.

Subscribers who haven’t texted any preference keyword have no tag set and won’t appear in a fall = true segment. Plan your preference center as opt-in by default, and use your welcome message or website to seed initial preferences.

​

Setting up a preference center

Go to Settings > Platforms > SMS Settings > Keywords and create a keyword pair for each subscription list, one to subscribe and one to unsubscribe. Subscribe keyword (e.g., FALL):

1. Enter the keyword text (e.g., FALL).
2. Select or create a reply template (e.g., “You’re subscribed to Fall promotions! Text NOFALL to unsubscribe anytime.”).
3. Assign a data tag: fall = true.

Unsubscribe keyword (e.g., NOFALL):

1. Enter the keyword text (e.g., NOFALL).
2. Select or create a reply template (e.g., “You’ve been unsubscribed from Fall promotions. Text FALL to resubscribe anytime.”).
3. Assign a data tag: fall = false.

Repeat this pair for each list. For a Spring list, create SPRING (spring = true) and NOSPRING (spring = false).

​

Targeting subscribers by preference

When building a campaign or Journey, use the User Tag filter in Segments. Choose the model that fits your program:

• Opt-in only: Filter on fall = true. Reaches only subscribers who actively texted FALL. Subscribers with no fall tag are excluded.
• Opt-out: Exclude fall = false. Reaches every subscriber on the sender except those who texted NOFALL, including subscribers who have never used the preference center.

These produce different audiences. Pick one model per program and apply it consistently.

​

Promoting your preference center

Tell subscribers which keywords are available in your welcome message (e.g., “Text FALL for Fall deals, SPRING for Spring deals, or STOP to unsubscribe from all.”) or on your website or app with a checklist that adds a data tag when a subscriber toggles on specific preferences.

---

​

FAQ

​

Can I use keywords with alphanumeric sender IDs?

No. Alphanumeric sender IDs are one-way only and cannot receive inbound messages, which means keywords are not available. You’ll need a sender resource type that supports inbound replies (long code, short code, toll-free, or RCS).

​

How do I know if reply syncing is enabled?

Go to Settings > Platforms > SMS Settings > Senders and check Setup Replies for each sender. Without reply syncing, OneSignal cannot receive inbound keywords and data tags will not be applied.

​

If I’m integrating with Twilio, does syncing keywords to OneSignal break my existing Twilio replies?

Yes. Syncing keywords to OneSignal will break any Twilio replies you have currently set up. If you rely on Twilio-side keyword handling, evaluate whether to migrate that logic to OneSignal or keep it in Twilio before enabling sync.

​

How many keywords can I create?

There is no documented limit, but keep your keyword list manageable. Every keyword you create should be promoted somewhere subscribers can find it, or it won’t be used.

​

Can I trigger a Journey from a keyword reply?

Yes. Assign a data tag to the keyword, then use a User Tag filter as the entry condition for a Journey. When the tag is set, eligible subscribers enter the Journey.

​

Can I use numbers as keywords for multiple-choice polls?

Yes, but with caution. Keywords are global to a sender, so 1, 2, and 3 will match for every campaign using that sender. If two concurrent campaigns both use 1, replies will trigger whichever keyword’s tag and template are configured — not the campaign the subscriber thought they were replying to. Prefer short letter mnemonics (e.g., EA, VIP, FALL) for poll responses.

---

​

Related pages