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, Amazon Pinpoint 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 AWS Support. AWS 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.

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 [phone]."

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. After your number receives an SMS message that contains an opt-out keyword, Amazon Pinpoint 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."

Note

If a recipient responds with one of these keywords as the first word of their message, Amazon Pinpoint SMS responds with the response for that keyword. For example, if a recipient responds to one of your messages with "Help me understand what this means," then Amazon Pinpoint SMS responds with the response that you specified for the HELP keyword.

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 Amazon Pinpoint 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. For more information on adding keywords, see Manage keywords.

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.

• 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.

Manage keywords

Use the Amazon Pinpoint SMS console or AWS CLI to customize the keyword responses for your phone number.

Add a keyword (Console)

Use the Amazon Pinpoint SMS console to add keywords to your pool.

Add a keyword

1. Open the Amazon Pinpoint SMS console at https://console.aws.amazon.com/sms-voice/.

2. In the navigation pane, under Configurations, choose Phone pools.

3. On the Phone Pools page, choose the pool to add a keyword to.

4. On the Keywords tab, choose Add keyword.

5. 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.

6. Choose Add keyword.

Edit a keyword (Console)

Use the Amazon Pinpoint SMS console to edit keywords in your pool.

To edit a keyword

1. Open the Amazon Pinpoint SMS console at https://console.aws.amazon.com/sms-voice/.

2. In the navigation pane, under Configurations, choose Phone pools.

3. On the Phone Pools page, choose the pool that contains the keyword.

4. On the Keywords tab, choose the keyword to edit and then Edit keyword.

5. 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.

6. Choose Save keyword.

Delete a keyword (Console)

Use the Amazon Pinpoint SMS console to delete keywords in your pool.

Note

Required opt-out keywords can't be deleted.

To delete a keyword

1. Open the Amazon Pinpoint SMS console at https://console.aws.amazon.com/sms-voice/.

2. In the navigation pane, under Configurations, choose Phone pools.

3. On the Phone Pools page, choose the pool that contains the keyword.

4. On the Keywords tab, choose the keyword and then Remove keyword.

Add or edit a keyword (AWS CLI)

You can use the put-keyword 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.

List keywords (AWS CLI)

You can use the 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.

Delete a keyword (AWS CLI)

You can use the delete-keyword 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.