AWS Messaging & Targeting Blog
Automate AWS End User Messaging US toll-free Number Registrations
Introduction:
AWS End User Messaging enables customers to send SMS messages to recipients located across the globe.
If you are planning on rolling out SMS across multiple countries, we recommend reviewing this blog. When you send SMS or MMS messages using AWS End User Messaging SMS, you must use a specific origination identity that supports the sending of SMS. In the US the originators that are supported are Toll-Free(TFN), 10DLC, and short codes and each of these has its own registration process.
This blog discusses the process of programmatically registering Toll-Free numbers (TFNs), which can be used exclusively within the United States. TFNs have a max throughput of 3 Messages Per Second(MPS) and are typically used for low-volume/throughput use cases. You can learn more about TFNs here.
TFNs have a relatively simple registration process, however, for Independent Software Vendors (ISVs), SaaS providers, or large organizations with many teams or use cases, completing dozens, or hundreds of TFN registrations manually can be time-consuming, tedious, and error-prone. AWS End User Messaging APIs can be used to streamline the TFN registration process by enabling AWS customers to programmatically register TFNs in the USA. You can learn more about the TFN registration requirements and process here.
In this post, we will discuss the AWS End User Messaging APIs required for programmatically registering TFNs. We’ll explore a simple Bash script you can use to automate the registration of a single TFN, as well as a Python script that you can use to bulk register multiple TFNs. Both of these scripts help simplify the TFN registration process and can save both time and effort for businesses looking to leverage AWS End User Messaging for their communication needs.
Outline of the APIs used in the scripts:
There are seven actions that need to be taken in order for a TFN registration to be created and submitted. The two scripts in this post automate these actions:
- create-registration
- Creates a new registration
- The “RegistrationType” field controls whether this is a registration for a Toll-Free, or 10DLC or a SenderID.
- describe-registration-field-definitions
- Retrieves the specified RegistrationType field definitions.
- You can use
DescribeRegistrationFieldDefinitions
to view the requirements for creating, filling out, and submitting each registration type. In this post we have chosen Toll-Free and provided the values.
- create-registration-attachment
- The carriers require you to provide a mockup that closely resemble the opt-in experience that your customers will complete to ensure end-users have consented to receiving SMS messages from this toll-free number. This should be a screenshot of your website or mobile application’s opt-in workflow.
- The maximum file size is 500kb, and valid file extensions are PDF, JPEG, or PNG.
- You need to wait until the attachment is uploaded before moving to step 4.
- put-registration-field-value
- This action needs to be repeated for all required fields (retrieved in step 2)
- request-phone-number
- Request an origination phone number for use in your account (needed for step 6)
- create-registration-association
- This associates the registration with the origination identity (phone number) you requested in step 5.
- You will need the PhoneNumberId for the origination identity.
- submit-registration-version
- This will submit the specified registration for review and approval
- IMPORTANT:
- Make sure that all of your data is correct, especially before attempting to submit multiple registrations using the second script option below.
- Once your script has submitted the registration, it’s initial status will be “CREATED” and should change to “REVIEWING” within 24 hours.
- Once submitted, you will be unable to edit or delete this registration until it is approved or rejected by the third-party registrar that controls the registration process for the type of registration you are submitting (in this blog we’re registering TFNs).
- You begin incurring costs for the TFNs as soon as you request the phone number, even if your registration is not submitted or is not approved.
No matter which script you decide to use, it’s important to keep a these things in mind:
- The registration information you provide will be reviewed by a third-party company. This is standard, no matter which provider you use for SMS
- While AWS submits the registration on your behalf, we do not participate in the actual review process, nor can we influence the third-party.
- The review process for TFNs can take up to 15 business days and if the information provided in the registration process is incomplete, inaccurate, or the use case falls into a forbidden category (Guidelines for using toll-free numbers) , the application can be rejected.
- If your toll-free number registration is rejected, the status of your registration will change to “Requires Updates“. We recommend monitoring your registration status frequently to ensure that you do not miss an update and extend the time it takes to complete.
- If updates are required, see Editing, discarding and deleting your registration. You can submit a request for information about a rejected toll-free number via the AWS Management Console > Support Center.
Prerequisites for either approach:
Before running either script, you’ll need:
- An AWS account with permission to use/provision the AWS End User Messaging service (link) in the target region.
The following information for each TFN you wish to register/request (you can retrieve this list with describe-registration-field-definitions API):
Company Info
- Company Name
- Website
- Address 1
- Address 2 (optional)
- City
- State / Province
- Zip Code / Postal Code
- Country Code
Contact Info
- First Name
- Last Name
- Support Email
- Support Phone Number
Messaging Use Case
- Monthly Message Volume (you must use one of the options below)
- “10”
- “100”
- “1,000”
- “10,000”
- “100,000”
- “250,000”
- “500,000”
- “750,000”
- “1,000,000”
- “5,000,000”
- “10,000,000+”
- Use Case Category (you must use one of the options below)
- “Two-factor authentication”
- “One-time passcodes”
- “Notifications”
- “Polling and surveys”
- “Info on demand”
- “Promotions & marketing”
- “Other”
- Use Case Details
- Opt-In Description – The primary purpose of the Opt-in Description is to demonstrate that the end user explicitly consents to receive text messages and understands the nature of the program. Your application is being reviewed by a 3rd party reviewer, so make sure to provide clear and thorough information about how your end-users opt-in to your SMS service and any associated fees or charges. If the reviewer cannot determine how your opt-in process works then your application will be denied and returned. If your Opt-in process requires a log-in, is not yet published publicly, is a verbal opt-in, or if it occurs on printed sources such as fliers and paper forms then make sure to thoroughly document how this process is completed by the end-user receiving messages. Provide a screenshot and host the screenshot on a publicly accessible website (like OneDrive or Google Drive) and provide the URL in the text as well as in the Opt-In Image below.
- Opt-In Image – This is optional, but highly recommended, even if you provide a description above:
- If your experience is not publicly available, the carriers will require you to provide one to ensure end-users have consented to receiving SMS messages from this toll-free number.
- You are encouraged to provide a screenshot (PDF, JPEG, or PNG) of your website or mobile application’s opt-in workflow. This could also be a screenshot of a paper form, a verbal opt-in script, or an as yet published website experience in development.
- The maximum file size is 500Kb.
Message Samples
- Message Sample 1
- Message Sample 2 (optional)
- Message Sample 3 (optional)
Option 1 – Execute a script to register a single TFN
The script requires the additional prerequisites (if you use AWS CloudShell to run the script, the AWS CLI and jq
are already installed).
AWS CLI
installed and configured with appropriate AWS account credentials and region (link)jq
(a lightweight and flexible command-line JSON processor) installed (link)
- Set environment variables for each of the required fields.
Before running the registration script, you must first set the necessary variables, replacing the placeholder values with your company actual data (these values are listed as a prerequisite above). Ensure that the opt-in screenshot image file optInImage.png
is in the same directory as the script, or provide the correct path to the image file in the attachment_body
variable. Note – the allowed file types for the opt-in screenshot are PNG, JPG, and PDF with a max file size of 500 kb.
Run the environment variable exports:
- Copy and save the below script as
register_us_toll_free_number.sh
into your current directory. Adjust theregion
variable in the script to the one you’re using to register the US TFN.
- Run
chmod
command to make it executable. Run the script with the environment variable values you provided in Step 1 above.
- The script completes with the following lines:
Option 2 – Execute a Python script to register more than one Toll-Free number
For ISVs, SaaS providers, or large organizations registering multiple phone numbers on behalf of customers or business units, automating the process can save time and reduce errors. We’ve chosen to use Python because it’s CSV library handles file parsing complexities, and its boto3 library enables seamless interaction with AWS services, making it well-suited for programmatically managing these registrations.
- Below is a sample CSV file with the variables for 5 registrations, copy it and replace the sample data with your actual data (these data were listed in the prerequisites above). Save your file as
data.csv
:
- Prepare opt-in screenshot image files for each registration, and upload them in the same directory as you will use for the
data.csv
and script files. Note: the allowed file types for the opt-in screenshot are PNG, JPG, and PDF with a max file size of 500 kb. - Below is a Python script to create registrations using the
data.csv
file (above). Save this file asregister_phone_numbers_bulk.py
into your current directory.
- Run the script:
python register_phone_numbers_bulk.py -c data.csv -r us-west-2
The 2 parameters are the name of the CSV file containing your data (shown here as data.csv) and specify the target AWS region (shown here as us-west-2) as parameters. Adjust these parameters as needed to match your environment and data location.
Check status:
Once you have successfully ran the script, you can check the status of your registration requests via AWS End User Messaging Console or with the API using the DescribeRegistrations API. If you want to use the console log in to the AWS End User Messaging Console in the target region and choose Configurations > Registrations from the left navigation. The registration status for each request will initially display “CREATED” and it will change to “REVIEWING” within 24 hours. As noted in the introduction, the actual registration review process is conducted by a third-party company and it can take up to 15 days to receive an acceptance (“COMPLETE”) or request for additional information or corrections (“Requires Update“) for each request.
Registration Status:
Phone Number Status:
Conclusion:
In this post you have learned how to automate the registration process for Toll-Free numbers with a Bash script or Python script and the AWS End User Messaging APIs. Using the API can significantly improve efficiency and reduce manual errors, but keep in mind that you will still need to wait up to 15 business days for the registrations to be approved (or not), and for the numbers to be set to “ACTIVE” status before you can begin sending messages with your TFN(s).
The AWS End User Messaging V2 API for SMS and Voice has other useful actions, and we encourage you to explore how it can further help you simplify and automate your applications.
Resources to help you plan for your SMS program:
Use this spreadsheet to plan for the countries you need to send SMS/MMS
To restrict your sending to only certain countries read this blog
Confirm the origination IDs you will need here
Check out the support tiers comparison