SMS Keyword Handling

Keywords are a foundational aspect of automated SMS messaging. With keywords, your users are able to message a list of single-word commands that do some type of action. For example, opting in and out of receiving SMS messages. With Braze, you also have the capability of setting custom keywords and groups that can be leveraged for more marketing options. Read more about our new SMS keyword handling process below.

Default Opt-In/ Opt-Out Keywords

Regulations require that there are responses to all opt-in, opt-out, and help/info keyword responses. Braze automatically processes the following exact, single-word, case-insensitive messages, automatically updating the Subscription Group state for the user and their associated phone number on all inbound requests.

To support this, Braze has the following keyword categories, each with its own keyword set and action that will take effect once we receive an inbound SMS requests. Note that these default keywords and responses can also be customized.

Type	Keyword	Change
Opt-In	START YES UNSTOP	Any inbound request with one of these Opt-In keywords will result in a Subscription Group state change to subscribed. Additionally, the pool of numbers associated with that subscription group will now be able to send an SMS message to that customer. User will receive your defined Opt-In auto response.
Opt-Out	STOP STOPALL UNSUBSCRIBE CANCEL END QUIT	Any inbound request with one of these Opt-In keywords will result in a Subscription Group state change to unsubscribed. Additionally, the pool of numbers associated with that Subscription Group will no longer be able to send an SMS message to that customer. User will receive your defined Opt-Out auto response.
Help	HELP INFO	User will receive your defined Help auto response.

Only the exact, single-word message will be processed (case insensitive). Keywords such as STOP PLEASE will be ignored.

Editing Keywords

If you would like to edit the default keywords set by Braze and add a new keyword to trigger an Opt-In, Opt-Out, or Help action, you can do this by navigating to your SMS subscription group and clicking into the group to edit your settings:

Here, you will see the default keywords and responses and have the option to modify those responses by clicking the “Edit” icon to the right of each keyword category.

This will bring up an edit modal to allow you to add keywords or modify responses. Note that Braze enforces global keywords (e.g START, YES, UNSTOP) to be set so these defaults cannot be changed. Please read the rules below that apply to keywords and keyword responses.

Keywords	Keyword Responses
- Valid UTF8 encoded characters - Maximum of 20 keywords per category total - Maximum length of 34 characters - Minimum length of 1 character - Cannot contain spaces - Required to be case insensitive and unique across the subscription group	- Cannot be blank - Maximum length of 300 characters - Valid UTF8 characters

Multi-Language Support

When sending to certain countries, a sender may be required to support inbound keywords and outbound replies with a local language. To support this, Braze allows you to create a language-specific keyword setting.

To get started, click “Add A Language” and select your target language or search for a language within the dropdown.

Please note that other languages do NOT come with preset keywords/responses like English, so senders will need to work with their marketing and legal teams to add any required keywords to this set. Otherwise, Braze will not handle localized incoming messages for those languages. If you need to delete a language, click the “Delete Language” button at the bottom right.

Custom Keyword Categories

In addition to the three default keyword categories (Opt-in, Opt-out, and Help), you are also able to create up to 10 of your own keyword categories. This allows you to identify arbitrary keywords and set up responses specific to your business. An example category might be “PROMO” or “DISCOUNT” which might prompt a response about promos that are happening this month.

These custom keywords operate in an “always-on” capacity, meaning that any user subscribed to your message service can text keywords and receive a response at any point. In addition to this behavior, you also have the option to define specific keywords that can only be sent to at certain points of your user’s lifecycle.

Create a Custom Category

To create a custom keyword category, edit the appropriate subscription group, and click “Add Custom Keyword Category”. Here, you will be able to provide a keyword category name and define which keywords a user can text in to receive the reply message.

Once created, this keyword category will be available to filter and trigger against in your campaigns and Canvases.

Keywords created in custom keyword categories adhere to all of the rules and validations stated above for the creation of new keywords.

Lifecycle Specific Keywords

If you have a use case where you would like to limit when a customer can send a specific keyword during their lifecycle (e.g during their first initial onboarding) to receive a response, you can use the trigger “Send inbound SMS to subscription group within keyword category OTHER” in your campaign/Canvas and define some ad-hoc keywords that your users can send in at a point in time.

Canvas

Campaign

Retargeting

In addition to changing the user’s subscription state and sending auto-responders based on incoming keywords, Braze will also record interactions to the user profile for filtering and triggering messages.

Filter by Recency

Filter for the recency of a user responding to your SMS Program. This filter will evaluate the LAST date a user sent an inbound SMS that is within one of the keyword categories.

Trigger Messages by Keyword

Messages can be triggered as users send messages inbound based on keyword categories (user sent any one of the keywords) or other keywords (user sent a keyword that does not fall into one of the existing categories). These triggers are set in the Delivery step of the campaign builder.

Trigger by Inbound Keyword Category

Trigger by Arbitrary Keywords
Note triggering a message on an “Other” keyword response, you will have the opportunity to evaluate the keyword body on an exact text match. This match follows the same rules as noted above: Only the exact, single-word message will be processed (case insensitive). A keyword sent of Hello Braze! would not match the criteria shown in the example below.

Template Keywords
When triggering a Campaign or Canvas Step on an inbound SMS, you can optionally template the text that your user sent into the body of your Campaign or Canvas with Liquid. This will enable you to access the user’s response which you can then include in your reply, apply conditional logic to, or anything else you can do with Liquid.

Currents Event

Any inbound SMS event will also be sent as a Currents event through the SMS InboundReceived event. This will allow you to perform additional actions or reporting on the messages your users are texting in outside of the Braze platform. Please note that inbound messages are truncated past 1600 characters.