SMS message settings for Amazon Cognito user pools - Amazon Cognito

SMS message settings for Amazon Cognito user pools

Some Amazon Cognito events for your user pool might cause Amazon Cognito to send SMS text messages to your users. For example, if you configure your user pool to require phone verification, Amazon Cognito sends an SMS text message when a user signs up for a new account in your app or resets their password. Depending on the action that initiates the SMS text message, the message contains a verification code, a temporary password, or a welcome message.

Amazon Cognito uses Amazon Simple Notification Service (SNS) for delivery of SMS text messages. If this is the first time that you are sending a text message through Amazon Cognito or Amazon SNS, you will be placed in a sandbox environment in Amazon SNS. This will allow you to test your applications for SMS text messages. In the sandbox, messages can be sent only to verified phone numbers.

Setting up SMS messages for the first time in Amazon Cognito user pools

Amazon Cognito uses Amazon SNS to send SMS messages to your user pools. The first time that you set up Amazon SNS to send SMS text messages, your AWS account is placed in the Amazon SNS sandbox. Amazon SNS uses the sandbox to prevent fraud and abuse and to meet compliance requirements. In the sandbox, Amazon SNS imposes some restrictions. For example, you can send text messages to up to 10 phone numbers that you have verified with Amazon SNS. While your AWS account remains in the sandbox, do not use your Amazon SNS configuration for applications that are in production. When you're in the sandbox, Amazon Cognito can't send messages to your users' phone numbers.

To send SMS text messages to user pool users in production for the first time, you must complete the following tasks:

1. Confirm that you are in the SMS sandbox

2. Verify phone numbers for Amazon Cognito in Amazon SNS

3. Obtain an origination identity for sending SMS messages to U.S. phone numbers

4. Move your account out of Amazon SNS sandbox

5. Finish setting up the user pool in Amazon Cognito

STEP 1: Confirm that you are in the SMS sandbox

  1. Sign in to the AWS Management Console and open the Amazon Cognito console at https://console.aws.amazon.com/cognito.

  2. Create a new user pool or edit an existing user pool.

  3. If your account is in the SMS sandbox, you will see the following message in Amazon Cognito.

    You are currently in a Sandbox environment in Amazon SNS.

    If you don’t see this message, then someone already performed the necessary steps to set up SMS messages for the first time in your account. Skip to STEP 5: Complete user pool setup in Amazon Cognito.

  4. Choose the Amazon SNS link in the message to open the Amazon SNS console in a new tab.

  5. Verify that you are in the sandbox environment. The console message will indicate your sandbox status and AWS Region. For example:

    This account is in the SMS sandbox in US East (N. Virginia).

In most AWS Regions, SMS messages from your user pool are routed through Amazon SNS in the same region. SMS messages in the following Amazon Cognito Regions are rerouted through the corresponding supported Amazon SNS Regions.

Amazon Cognito Regions Supported Amazon SNS Regions
US East (Ohio) US East (N. Virginia)
Asia Pacific (Mumbai) Asia Pacific (Sydney)
Asia Pacific (Seoul) Asia Pacific (Tokyo)
Canada (Central) US East (N. Virginia)
Europe (Frankfurt) Europe (Ireland)
Europe (London) Europe (Ireland)

STEP 2: Verify phone numbers for Amazon Cognito in Amazon SNS

To verify SMS destination phone numbers for testing with your application, you must add destination phone numbers to Amazon SNS and then verify the numbers. For detailed instructions, see Adding and verifying phone numbers in the SMS sandbox in the Amazon Simple Notification Service Developer Guide.

Note

There is a limit to the number of destination phone numbers you can add to the sandbox. For details, see SMS sandbox in the Amazon Simple Notification Service Developer Guide.

STEP 3: Obtain an origination identity for sending SMS messages to US phone numbers

If you plan to send SMS text messages to U.S. phone numbers, you must obtain an origination identity.

Starting June 1, 2021, U.S. carriers require an origination identity to send messages to U.S. phone numbers. If you do not already have an origination identity, you must get one. To learn how to obtain an origination identity, see Requesting a number in the Amazon Pinpoint User Guide.

If you operate in the following AWS Regions, you must open an AWS Support ticket to obtain an origination identity. For instructions, see Requesting support for SMS messaging in the Amazon Simple Notification Service Developer Guide.

  • Europe (Stockholm)

  • Middle East (Bahrain)

  • Europe (Paris)

  • South America (São Paulo)

  • US West (N. California)

STEP 4: Move your account out of Amazon SNS sandbox

When your account is in the SMS sandbox in Amazon SNS, Amazon Cognito can send SMS text messages to only verified phone numbers and not to your end users.

To send SMS messages to end users, you must move your account out of the sandbox and into production. For detailed instructions, see Moving Out of the Amazon SNS Sandbox in the Amazon Simple Notification Service Developer Guide.

STEP 5: Complete user pool setup in Amazon Cognito

Return to the browser tab where you were creating or editing your user pool. Complete the procedure.