# SMS keywords

{{< glossary_definition "sms_keyword" >}}

Use keywords to:

* Opt users in to messaging campaigns based on their keyword-indicated interests.
* Drive loyalty with unique keywords for loyalty members and non-members.
* Trigger external processes, e.g., a chatbot, using webhooks.
* Provide directions or access to promotional information, coupons, etc.
* Target future messaging based on keyword generated tags or subscription lists.

You can define opt-in keywords that will opt the user in to receiving SMS notifications or trigger opt-in flows. By default, users can text any of these words to opt out of notifications: `STOP`, `STOPALL`, `UNSUBSCRIBE`, `CANCEL`, `END`, `QUIT`, `ARRET`. You can also add additional opt-out keywords. See: [Opt-In/Out Handling](https://www.airship.com/docs/developer/api-integrations/sms/opt-in-out-handling/).

Mobile-originated messages are represented as [Events](https://www.airship.com/docs/reference/glossary/#events). Each event records the keywords that your audience uses and additional identifying information. You can use these events to observe opt-in and opt-out trends in [Performance Analytics](https://www.airship.com/docs/reference/glossary/#pa) or to get events directly from [Real-Time Data Streaming](https://www.airship.com/docs/reference/glossary/#rtds). 

<!-- Moved from deleted /platform page. Not yet released for self-service in dashboard.

## Keyword features

* **Fallback response** — Create a custom reply for undefined incoming keywords or messages.
* **Active time frame** — Set a date range for when keywords are active, and optionally create a custom response when a keyword is used before or after the active time frame.

-->

> **Important:** Before implementing changes to compliance keywords (e.g., HELP and STOP), please consult your legal counsel in order to address your specific use case or regulatory requirements in your jurisdiction. Certain compliance keywords may be required in certain jurisdictions or under the local carrier requirements.


## Keyword format

When you create a keyword, you must configure the following:

* **Keyword** — The word that triggers the response text and opt-in action, e.g., `JOIN` or `YES`. 
   * Must be unique per sender ID
   * 100 characters maximum
   * Cannot contain spaces
   * Case insensitive
* **Response** — The text that is sent to a user when they reply with the keyword or alias. You can select a pre-configured [webhook](https://www.airship.com/docs/developer/api-integrations/sms/inbound-message-handling/) as an alternative or in addition to the response text.
* **Sender** — A [Sender ID](https://www.airship.com/docs/reference/glossary/#sender_id). **You must have at least one sender ID configured in your project before you can create keywords.**

You can also configure these options:

* **Alias** — Alternatives to the keyword. Must be unique per sender ID. Aliases have the same formatting requirements and restrictions as keywords.
* **Opt-in action** — The event that occurs when a user replies with the keyword or alias: *None*, *Opt in*, *Opt out*, or *Create channel without opting in*.
* **Tags** — Add or remove [Tags](https://www.airship.com/docs/reference/glossary/#tag) when a user replies with the keyword or alias.
* **Shorten links** — When enabled, if your response includes URLs (beginning with `http://` or `https://`), they will be converted to [shortened links](https://www.airship.com/docs/reference/glossary/#sms_link_shortening).
* **Subscription lists** — Opt a user in to or out of [Subscription Lists](https://www.airship.com/docs/reference/glossary/#subscription_list). See: [Subscription List Opt In/Out](#opt-in).
* **Webhook** — You can select a pre-configured [webhook](https://www.airship.com/docs/developer/api-integrations/sms/inbound-message-handling/) as an alternative or in addition to the response text.

## Create keywords

1. Go to **Messages**, then **SMS Keywords**.
1. Select **** in the map or ** Create new keyword**.
1. Enter the keyword and aliases. Click **Add** after entering each alias.
1. Click *Keyword action 
* or select the *Response* card in the map.
1. Enter the response text. You can leave this field empty if you are configuring a webhook instead.
1. Configure options:
   * *Shorten links* — Toggle to enable.
   * *Opt-in action* — Make a selection.
   * *Webhook* — Make a selection. A selection is required if you are omitting response text.
   * *Tags* — Select *Add* or *Remove*, enter a tag name in the search field, then:
      * If searching for an **existing tag**, click to select from the search results. Search for existing tags returns all custom tag groups that contain that tag.
      * If creating a **new tag**, click **Create new tag: [search term]**, enter a [custom tag group](https://www.airship.com/docs/guides/audience/tags/#custom-tag-groups) name in the search field that appears, then click to to select from the search results.
   * *Subscription lists* — Select *Opt in to* or *Opt out of*, search for a subscription list and select from the results. Repeat for multiple lists.
1. Click **Settings** and select a sender ID. Each sender ID in the list is prepended with its country.
1. Click **Save** and confirm.

## Manage keywords

To view the list of the keywords in your project, go to **Messages**, then **SMS Keywords**.

* Keywords are grouped by sender ID.
* Sender IDs are sorted numerically then alphabetically. Keywords are sorted by creation order.
* You can filter the list by searching for keyword, alias, or sender ID.

You can edit all fields and selections in an existing keyword:

1. Select a keyword from the list.
1. Make your changes.
1. Click **Save** and confirm.

To delete a keyword:

1. Select a keyword from the list.
1. Click **Settings**.
1. Click **Delete keyword** and confirm.