Request a phone number

Using the Amazon Pinpoint SMS console, we’ll recommend one of the below origination identities depending on your use-case. Recommendations are based on your input criteria including if you require SMS and/or voice capabilities, a two-way number, and estimate monthly messages.

Note

The following phone number types have to be requested in the Support Center Console.

• Short codes – Requesting short codes for SMS messaging with Amazon Pinpoint SMS.

• Long codes – Requesting dedicated long codes for SMS messaging with Amazon Pinpoint SMS.

You can use either the Amazon Pinpoint SMS console or AWS CLI to request a new phone number.

Request a phone number (Console)

To request a phone number using the Amazon Pinpoint SMS console, follow these steps:

Request a phone number (Console)

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

2. In the navigation pane, under Configurations, choose Phone numbers and then Request originator.

3. On the Select country page you must choose the Message destination country from the drop down that messages will be sent to. Choose Next.

4. On the Messaging use case section, enter the following:

   • Under Number capabilities choose either SMS, Voice or both depending on your requirements.

     Important

     Capabilities for SMS and Voice can't be changed once the phone number has been purchased.

     • SMS – Choose if you need SMS capabilities.

     • Voice (text to audio) – Choose if you need voice capabilities.

   • Under Estimated monthly SMS message volume per month – optional choose the estimated number of SMS messages you will send each month.

   • For Company headquarters - optional choose either of the following:

     • Local – Choose this if your companies headquarters is in the same country as your customers who will revive SMS messages. For example, you would choose this option if your headquarters is in the United States and your users who will receive messages are also in the United States.

     • International – Choose this if your companies headquarters is not in the same country as your customers who will revive SMS messages.

   • For Two-way messaging choose Yes if you require two-way messaging.

5. Choose Next.

6. Under Select originator type choose either the recommend phone number type or one of the available number types. The available options are based on the use case information you filled out in the previous steps.

   If you choose 10DLC and already have a registered campaign you can choose the campaign from the Associate to registered campaign to add the 10DLC phone number to the 10DLC campaign.

   If the number type you want isn't available you can choose Previous to go back and modify your use case. Also check the Supported countries and regions (SMS channel) to make sure the originator type you want is supported in the destination country.

   If you want to request a short code or long code you need to open a case with AWS Support. For more information, see Requesting short codes for SMS messaging with Amazon Pinpoint SMS and Requesting dedicated long codes for SMS messaging with Amazon Pinpoint SMS.

7. Choose Next.

8. On Review and request you can verify and edit your request before submitting it. Choose Request.

9. A Registration Required window may appear depending on the type of phone number you requested. Your phone number or sender ID is associated with this registration and can't send messages until your registration has been approved. For more information about registrations requirements see Registrations.

   1. For Registration form name enter a friendly name.

   2. Choose Begin registration to finish registering the phone number or Register later.

      Important

      Your phone number or sender ID can't send messages until your registration has been approved.

      You are still billed the recurring monthly lease fee for the phone number regardless of registration status. For more information about registrations requirements see Registrations.

Request a phone number (AWS CLI)

You can use the request-phone-number command to add new phone numbers to your account. Phone number availability and supported features vary by country.

Important

You may need to register the phone number or sender ID after you complete the request. You are still billed the recurring monthly lease fee for the phone number regardless of registration status. For more information about registrations requirements see Registrations.

To request a phone number

• At the command line, enter the following command:

  $ aws pinpoint-sms-voice-v2 request-phone-number \
  > --iso-country-code XX \
  > --message-type TRANSACTIONAL \
  > --number-capabilities VOICE \
  > --number-type LONG_CODE \
  > --pool-id poolId \
  > --deletion-protection-enabled \
  > --opt-out-list-name optOutListName \
  > --registration-id CO123EX

  In the preceding command, make the following changes:

  • Replace XX with the two-letter ISO-3166 alpha-2 code for the country of the phone number (such as CA for Canada).

  • If you want to use the phone number to send promotional or marketing-related content, replace TRANSACTIONAL with PROMOTIONAL. Otherwise, use TRANSACTIONAL.

  • If you want to request a phone number for sending SMS messages, replace VOICE with SMS. You can also request a phone number that can be used to send both SMS and voice messages by specifying SMS VOICE.

  • Replace LONG_CODE with the type of phone number you want to request. Acceptable values are LONG_CODE, TOLL_FREE, and TEN_DLC.

  • Replace poolId with the ID or Amazon Resource Name (ARN) of the pool that you want to add the phone number to. This parameter is optional. If you don't want to add the phone number to a pool, omit this parameter.

  • If you want to enable deletion protection for this phone number, add the --deletion-protection-enabled parameter. Deletion protection is disabled by default. If deletion protection is enabled, you can't delete the phone number using the ReleasePhoneNumber API, unless you update the configuration of the phone number to disable this feature.

  • Replace optOutListName with the name or ARN of the opt-out list that you want to associate with the phone number. This parameter is optional. If you don't want to associate the phone number with an opt-out list, omit this parameter.

  • If you're requesting a phone number to use with a 10DLC campaign, replace CO123EX with the ID of the 10DLC campaign that you want to use.

    Note

    If you plan to use a 10DLC phone number, you must first register your company and campaign. Currently, the only way to complete these registration processes is to use the Amazon Pinpoint SMS console. For more information about 10DLC registration, see 10DLC registration process.

If the number is successfully added to your account, you see output similar to the following:

{
    "PhoneNumberArn": "arn:aws:sms-voice:us-east-1:111122223333:phone-number/phone-615790209ea34aea8da9b729fexample",
    "PhoneNumberId": "phone-615790209ea34aea8da9b729fexample",
    "PhoneNumber": "[phone]",
    "Status": "PENDING",
    "IsoCountryCode": "CA",
    "MessageType": "TRANSACTIONAL",
    "NumberCapabilities": [
        "SMS"
    ],
    "NumberType": "LONG_CODE",
    "MonthlyLeasingPrice": "1.00",
    "TwoWayEnabled": false,
    "SelfManagedOptOutsEnabled": false,
    "OptOutListName": "Default",
    "DeletionProtectionEnabled": false,
    "CreatedTimestamp": 1645568542.0
}

Note

When you first purchase a phone number, the value of the Status attribute is PENDING. When the phone number is ready to use, the value of Status changes to ACTIVE.

If a phone number that meets the parameters you specified isn't available, the request fails with an error.

Modify phone number capabilities (AWS CLI)

After you request a phone number, you can use the update-phone-number CLI to change the settings of that phone number, or to enable additional features. You can change several phone number settings, including the pool and opt-out list that are associated with the phone number, as well as the deletion protection setting.

An example of an additional feature that you can enable by updating a phone number is two-way messaging. Support for two-way messaging varies depending on which country you plan to send messages to. For a list of supported countries, see Supported countries and regions (SMS channel).

$ aws pinpoint-sms-voice-v2 update-phone-number \
> --phone-number-id phone-d2b0f5dd4fd14ebdb2a3b9128example \
> --deletion-protection-enabled true \
> --opt-out-list-name optOutListName \ 
> --self-managed-opt-outs-enabled true \
> --two-way-enabled true \
> --two-way-channel-arn arn:aws:sns:us-east-1:111122223333:MyTopic

In the preceding command, do the following:

• Replace phone-d2b0f5dd4fd14ebdb2a3b9128example with the PhoneNumberID or the Amazon Resource Name (ARN) of the phone number that you want to update. You can find both of these values by using the DescribePhoneNumbers operation.

• Replace optOutListName with the name of the opt-out list that you want to associate with this phone number.

• If you want to disable the deletion protection feature, change the value of the DeletionProtectionEnabled parameter to false.

• If you want to self-managed SMS opt-outs feature, change the value of the SelfManagedOptOutsEnabled parameter to false.

• If you want to disable two-way SMS messaging for this phone number, change the value of the TwoWayEnabled parameter to false.

• If you enable the two-way messaging feature for the phone number, you must specify the ARN of an Amazon SNS topic. Replace arn:aws:sns:us-east-1:111122223333:MyTopic with the ARN of the Amazon SNS topic that you want to use. When you receive incoming messages, they are sent to the topic that you specify.

The PhoneNumberId parameter is the only required parameter for this command. You can omit any of the other parameters if you don't want to change the corresponding settings.

List phone numbers (AWS CLI)

You can use the describe-phone-numbers to get more information about the origination phone numbers in your Amazon Pinpoint account.

To list all of the phone numbers in your account using the AWS CLI

• At the command line, enter the following command:

  $ aws pinpoint-sms-voice-v2 describe-phone-numbers

The output of this command includes details about all of the phone numbers in your account. You can also view information about specific phone numbers by including the PhoneNumberId parameter.

To view information about a specific phone number using the AWS CLI

• At the command line, enter the following command:

  $ aws pinpoint-sms-voice-v2 describe-phone-numbers \
  >  --phone-number-id phone-d2b0f5dd4fd14ebdb2a3b9128example

In the preceding example, replace phone-d2b0f5dd4fd14ebdb2a3b9128example with the PhoneNumberID or the Amazon Resource Name (ARN) of the phone number that you want to view more information about.

You can also use the filter parameter to filter the list of phone numbers based on criteria that you define. For example, you can filter by the country of the phone number, or by its capabilities (that is, whether it supports SMS or voice messages, or both).

To view a filtered list of phone numbers using the AWS CLI

• At the command line, enter the following command:

  $ aws pinpoint-sms-voice-v2 describe-phone-numbers \
  > --filters Name=number-capability,Values=SMS \
  > --filters Name=iso-country-code,Values=CA

The filter Name can be any of the following values:

• status – The current status of the phone number, such as ACTIVE.

• iso-country-code – The two-character ISO-3166 alpha-2 code of the phone number's country.

• message-type – The type of messages that the phone number is used to send. Possible values are TRANSACTIONAL or PROMOTIONAL.

• number-capability – The messaging channels that the phone number supports. Possible values are SMS and VOICE.

• number-type – The type of phone number, such as LONG_CODE, SHORT_CODE or TOLL_FREE.

• two-way-enabled – A boolean that indicates whether or not two-way SMS messaging is enabled.

• self-managed-opt-outs-enabled – A boolean that indicates whether or not self-managed SMS opt-outs are enabled.

• opt-out-list-name – The name of the opt-out list associated with the phone number.

• deletion-protection-enabled – A boolean that indicates whether or not the phone number can be deleted using the DeletePhoneNumber operation.

Topics

• Phone number status
• Requesting short codes for SMS messaging with Amazon Pinpoint SMS
• Requesting dedicated long codes for SMS messaging with Amazon Pinpoint SMS

Phone number status

When you first purchase a phone number, the phone number's Number status is PENDING. When the phone number is ready to use, the phone number's status is ACTIVE. If the phone number requires registration then that must be completed before the phone number's Number status is changed to ACTIVE.

Phone number status

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

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

3. On the Phone numbers the phone number status is listed in the Number status column.

   • PENDING – The phone number is not ready for use. You may need register the phone number. For more information, see Registrations.

   • ACTIVE – The phone number is ready for use.