# Keywords in AWS End User Messaging SMS Keywords A *keyword* is a specific word or phrase that a customer can send to your phone number to elicit a response, such as an informational message, opting-in to receive more messages, a special offer and other promotional and transactional messages. When your number receives a message that begins with a keyword, AWS End User Messaging SMS responds with a customizable message. For short codes, the console shows the keywords and responses that you initially define when you request a short code from Support. Support registers your keywords and responses with wireless carriers when it provisions your short code. For long codes, the console shows the default keywords and responses. **Important** Your keywords and response messages must comply with the guidelines that are set by wireless carriers and wireless industry groups. Otherwise, following an audit, such groups might take action against your short code or long code. This action can include deny listing your number and blocking your messages. A keyword can be between 1 and 30 characters in length and can't start or end with a space. Keywords are case insensitive. For AWS RCS Agents, keywords are configured on the AWS RCS Agent and apply to all associated RCS for Business IDs (testing agent and country launch agents). When an end user sends a message containing a keyword to your AWS RCS Agent, AWS End User Messaging SMS responds with the configured keyword response. For more information about receiving inbound RCS messages and keyword handling, see [Receiving inbound RCS messages](rcs-inbound.md). Wireless carriers in the US require short codes to support the following keywords. In addition, AWS expects all long codes and short codes to support these keywords: HELP Used to obtain customer support. The response message must include customer-support contact information, as in the following example: *"For assistance with your account, call (206) 555-0199."* STOP Used to opt out of receiving messages from your number. In addition to *STOP*, your audience can use any supported opt-out keyword, such as *CANCEL* or *OPTOUT*. For a list of supported opt-out keywords, see [Required opt-out keywords](keywords-required.md). After your number receives an SMS message that contains an opt-out keyword, AWS End User Messaging SMS stops sending SMS messages from your account to the individual who opted out. The response message must confirm that messages will stop being sent to the individual who opted out, as in the following example: *"You are now opted out and will no longer receive messages."* **Topics** + [ # Required opt-out keywords ](keywords-required.md) + [ # Keyword actions ](keywords-actions.md) + [Add a keyword to a phone number](keywords-manage-phone-number.md) + [View the keywords used by a phone number](keywords-phone-number-list.md) + [Edit a keyword used by a phone number](keywords-phone-number-edit.md) + [Delete a keyword from a phone number](keywords-phone-number-delete.md) + [Add a keyword to a phone pool](keywords-pool-add.md) + [View keywords used by a phone pool](keywords-pool-list.md) + [Edit a keyword in a phone pool](keywords-pool-edit.md) + [Delete a keyword from a phone pool](keywords-pool-delete.md) # Required opt-out keywords Where required by local laws and regulations (such as in the US and Canada), SMS and MMS recipients can use their devices to opt out by replying to the message with any of the following: **Note** You can add custom keywords to phone numbers and phone pools to opt-out. + ARRET + CANCEL + END + OPT-OUT + OPTOUT + QUIT + REMOVE + STOP + TD + UNSUBSCRIBE To opt out, the recipient must reply to the same phone number that AWS End User Messaging SMS used to deliver the message. After opting out, the recipient no longer receives SMS or MMS messages from your AWS account. **Note** For US toll-free numbers, opt-outs are managed at the carrier level. The only supported opt-out keyword for a US toll-free number is STOP. You can't add additional opt-out keywords, or change the response message that your recipients get when they opt-out. A user can resubscribe by sending a new message to the toll-free using either UNSTOP or START as the keyword. To configure allowing a user to resubscribe add the keywords UNSTOP, START or both to your toll-free number and set the keyword action to `Opt-in`. # Keyword actions A keyword can have one of three actions associated with it. When a customer responds with the keyword the action will be performed to add or remove the user from the opt-out list or respond to the user with a message. + `Opt-out` – The recipient is added to the opt-out list and will not receive future messages. + `Opt-in` – The recipient wants to receive future messages. + `Automatic response` A message is sent to the recipient who send the text keyword message. # Add a keyword to a phone number in AWS End User Messaging SMS Add a keyword to a phone number Use the AWS End User Messaging SMS console or AWS CLI to customize the keyword responses for your phone number. ------ #### [ Add a keyword (Console) ] Use the AWS End User Messaging SMS console to add keywords to your phone number. **Add a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone number**. 1. On the **Phone number** page, choose the phone number to add a keyword to. 1. On the **Keywords** tab, choose the **Add keyword** button. 1. In the **Custom Keyword** pane add the following: + **Keyword** – The new keyword to add. + **Response message** – The message to send back to the recipient. + **Keyword action** – The action to perform when the keyword is received. 1. Choose **Add keyword**. ------ #### [ Add or edit a keyword (AWS CLI) ] You can use the [put-keyword](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/put-keyword.html) command to create a new keyword or edit. If the keyword already exists then it will be over written. To create a keyword, run the following command in the AWS CLI: ``` $ aws pinpoint-sms-voice-v2 put-keyword \ > --origination-identity OriginationIdentity \ > --keyword Keyword \ > --keyword-message KeywordMessage \ > --keyword-action KeywordAction ``` In the preceding command, make the following changes: + Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the phone number that you want to add the keyword to. + Replace *Keyword* with the new keyword. + Replace *KeywordMessage* with the message to use when responding to the keyword. + Replace *KeywordAction* the action (`AUTOMATIC_RESPONSE`, `OPT_OUT`, `OPT_IN`) to perform when the keyword is received. ------ # View the keywords used by a phone number in AWS End User Messaging SMS View the keywords used by a phone number You can use the [describe-keywords](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/describe-keywords.html) command to view information about the keywords associated with an origination identity. To view a list of keywords using the AWS CLI at the command line, enter the following command: ``` $ aws pinpoint-sms-voice-v2 describe-keywords \ > --origination-identity OriginationIdentity ``` In the preceding command, make the following changes: Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the phone number or sender ID that you want a list of keywords from. # Edit a keyword used by a phone number in AWS End User Messaging SMS Edit a keyword used by a phone number Use the AWS End User Messaging SMS console or AWS CLI to edit keyword responses for your phone number. ------ #### [ Edit a keyword (Console) ] Use the AWS End User Messaging SMS console to edit keywords. **To edit a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone number**. 1. On the **Phone number** page, choose the phone number that contains the keyword. 1. On the **Keywords** tab, choose the keyword to edit and then the **Edit keyword** button. 1. In the **Custom Keyword** pane modify any of the following: + **Keyword** – The keyword to change. + **Response message** – The message to send back to the recipient. + **Keyword action** – The action to perform when the keyword is received. 1. Choose **Save keyword**. ------ #### [ Add or edit a keyword (AWS CLI) ] You can use the [put-keyword](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/put-keyword.html) command to create a new keyword or edit. If the keyword already exists then it will be over written. To create a keyword, run the following command in the AWS CLI: ``` $ aws pinpoint-sms-voice-v2 put-keyword \ > --origination-identity OriginationIdentity \ > --keyword Keyword \ > --keyword-message KeywordMessage \ > --keyword-action KeywordAction ``` In the preceding command, make the following changes: + Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the phone number that you want to add the keyword to. + Replace *Keyword* with the new keyword. + Replace *KeywordMessage* with the message to use when responding to the keyword. + Replace *KeywordAction* the action (`AUTOMATIC_RESPONSE`, `OPT_OUT`, `OPT_IN`) to perform when the keyword is received. ------ # Delete a keyword from a phone number in AWS End User Messaging SMS Delete a keyword from a phone number Use the AWS End User Messaging SMS console to delete a keyword from your phone number. **Note** Required opt-out keywords can't be deleted. **To delete a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone numbers**. 1. On the **Phone numbers** page, choose the phone number that contains the keyword. 1. On the **Keywords** tab, choose the keyword to delete and then **Remove keyword**. # Add a keyword to a phone pool in AWS End User Messaging SMS Add a keyword to a phone pool Use the AWS End User Messaging SMS console or AWS CLI to customize the keyword responses for your phone pool. ------ #### [ Add a keyword (Console) ] Use the AWS End User Messaging SMS console to add keywords to your pool. **Add a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone pools**. 1. On the **Phone Pools** page, choose the pool to add a keyword to. 1. On the **Keywords** tab, choose **Add keyword**. 1. In the **Custom Keyword** pane do the following: + **Keyword** – The new keyword to add. + **Response message** – The message to send back to the recipient. + **Keyword action** – The action to perform when the keyword is received. 1. Choose **Add keyword**. ------ #### [ Add or edit a keyword (AWS CLI) ] You can use the [put-keyword](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/put-keyword.html) command to create a new keyword or edit. If the keyword already exists then it will be over written. To create a keyword, run the following command in the AWS CLI: ``` $ aws pinpoint-sms-voice-v2 put-keyword \ > --origination-identity OriginationIdentity \ > --keyword Keyword \ > --keyword-message KeywordMessage \ > --keyword-action KeywordAction ``` In the preceding command, make the following changes: + Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the pool that you want to add the keyword to. + Replace *Keyword* with the new keyword. + Replace *KeywordMessage* with the message to use when responding to the keyword. + Replace *KeywordAction* the action (`AUTOMATIC_RESPONSE`, `OPT_OUT`, `OPT_IN`) to perform when the keyword is received. ------ # View keywords used by a phone pool in AWS End User Messaging SMS View keywords used by a phone pool Use the AWS End User Messaging SMS console or AWS CLI to view the keyword responses for your phone pool. ------ #### [ View keywords (Console) ] Use the AWS End User Messaging SMS console to view keywords to your pool. **Add a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone pools**. 1. On the **Phone Pools** page, choose the pool. 1. On the **Keywords** tab, you can view the keyword, response message, and actions. ------ #### [ List keywords (AWS CLI) ] You can use the [describe-keywords](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/describe-keywords.html) command to view information about the keywords associated with an origination identity. To view a list of keywords using the AWS CLI at the command line, enter the following command: ``` $ aws pinpoint-sms-voice-v2 describe-keywords \ > --origination-identity OriginationIdentity ``` In the preceding command, make the following changes: Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the phone number or sender ID that you want a list of keywords from. ------ # Edit a keyword in a phone pool Edit a keyword in a phone pool Use the AWS End User Messaging SMS console or AWS CLI to edit keyword responses for your phone pool. ------ #### [ Edit a keyword (Console) ] Use the AWS End User Messaging SMS console to edit keywords in your pool. **To edit a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone pools**. 1. On the **Phone Pools** page, choose the pool that contains the keyword. 1. On the **Keywords** tab, choose the keyword to edit and then **Edit keyword**. 1. In the **Custom Keyword** pane modify any of the following: + **Keyword** – The keyword to edit. + **Response message** – The message to send back to the recipient. + **Keyword action** – The action to perform when the keyword is received. 1. Choose **Save keyword**. ------ #### [ Add or edit a keyword (AWS CLI) ] You can use the [put-keyword](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/put-keyword.html) command to create a new keyword or edit. If the keyword already exists then it will be over written. To create a keyword, run the following command in the AWS CLI: ``` $ aws pinpoint-sms-voice-v2 put-keyword \ > --origination-identity OriginationIdentity \ > --keyword Keyword \ > --keyword-message KeywordMessage \ > --keyword-action KeywordAction ``` In the preceding command, make the following changes: + Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the pool that you want to add the keyword to. + Replace *Keyword* with the new keyword. + Replace *KeywordMessage* with the message to use when responding to the keyword. + Replace *KeywordAction* the action (`AUTOMATIC_RESPONSE`, `OPT_OUT`, `OPT_IN`) to perform when the keyword is received. ------ # Delete a keyword from a phone pool in AWS End User Messaging SMS Delete a keyword from a phone pool Use the AWS End User Messaging SMS console or AWS CLI to delete a keyword from your phone pool. ------ #### [ Delete a keyword (Console) ] Use the AWS End User Messaging SMS console to delete keywords in your pool. **Note** Required opt-out keywords can't be deleted. **To delete a keyword** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Configurations**, choose **Phone pools**. 1. On the **Phone Pools** page, choose the pool that contains the keyword. 1. On the **Keywords** tab, choose the keyword and then **Remove keyword**. ------ #### [ Delete a keyword (AWS CLI) ] You can use the [delete-keyword](https://docs.aws.amazon.com/cli/latest/reference/pinpoint-sms-voice-v2/delete-keyword.html) CLI to delete a keyword. At the command line, enter the following command: ``` $ aws pinpoint-sms-voice-v2 delete-keyword \ > --origination-identity OriginationIdentity \ > --keyword Keyword ``` In the preceding command, make the following changes: + Replace *OriginationIdentity* with the unique ID or Amazon Resource Name (ARN) of the phone number or sender ID that you want to remove the keyword from. + Replace *Keyword* with the keyword to delete. ------