The following section gives examples of how to create, populate, and submit a registration
using the AWS CLI. For examples of how to create and submit a Toll-free phone number
registration using python or shell script, see Automate AWS End User Messaging US toll-free Number Registrations
Background
Some countries require you to register your company's identity to be able to purchase an origination identity and review the messages you send to recipients in their country.
-
The registration information you provide may be reviewed by a third-party. The third-party varies from country to country but could be a governmental regulatory agency or mobile carrier that perform the review.
-
The amount of time the third-party company takes to review your registration varies by registration type.
Prerequisites
Before you begin you must:
-
Install and configure the AWS CLI, see Configure the AWS CLI in the AWS Command Line Interface User Guide.
-
An AWS account with permissions to use AWS End User Messaging SMS in the target region.
-
A registrations AssociationBehavior specifies the order for when a registration can be associated with an origination identity and disassociated from an origination identity, see SupportedAssociation.
ASSOCIATE_BEFORE_SUBMITThe origination identity has to be supplied when submitting a registration.ASSOCIATE_ON_APPROVALThis applies to all sender ID registrations. The sender ID will be automatically provisioned once the registration is approved.ASSOCIATE_AFTER_COMPLETEThis applies to phone number registrations when you must complete a registration first, then associate one or more phone numbers later.
Important
Once you purchase an origination identity you are changed for it regardless of the registrations status, see AWS End User Messaging Pricing
. Once you submit your registration you can not make any changes to the registration or disassociate any resources with the registration until after it has been reviewed by a third party and returned back to you.
The following are additional resources for registrations.
Use the create-registration command to create a new blank registration. The RegistrationType parameter determines the type of registration to create. If you don't know the value for the type of registration you want to create then use the describe-registration-type-definitions command to retrieve a list of all registration types.
The following examples show how to create a Toll-free number registration form.
$ aws pinpoint-sms-voice-v2 create-registration --registration-type US_TOLL_FREE_REGISTRATION --tags "Key=Name,Value=MyTFNRegistration"On successful completion save the value of RegistrationId as it will be needed for other commands.
Note
To add a friendly name to your registration you must add a tag with the
Key set to Name and the
Value set to the friendly name to use.
You can also add tags to resources for billing purposes, see Tag resources for billing.
The following example is partial output of the
describe-registration-type-definitions command. Because AssociationBehavior is set to ASSOCIATE_BEFORE_SUBMIT
the toll-free number must be purchased and associated with the registration before
the registration can be submitted for approval. For more information on AssociationBehavior and DisassociationBehavior, see SupportedAssociation.
{
"RegistrationTypeDefinitions": [
{
"RegistrationType": "US_TOLL_FREE_REGISTRATION",
"SupportedAssociations": [
{
"ResourceType": "TOLL_FREE",
"IsoCountryCode": "US",
"AssociationBehavior": "ASSOCIATE_BEFORE_SUBMIT",
"DisassociationBehavior": "DISASSOCIATE_ALL_CLOSES_REGISTRATION"
}
],
"DisplayHints": {
"Title": "US toll-free number registration"
}
},
...Next you need to get the definitions for each field to know what the requirements are, such as the maximum number of characters for the field.
Each registration is divided into sections and each section has one or more fields. Use the describe-registration-field-definitions command to retrieve all section and field definitions for a registration. You will need the FieldPath for each field later to be able to set its value. Also FieldRequirement is used to determine if a field will be required or optional.
The following examples show how to retrieve field definitions for the Toll-free registration form.
$ aws pinpoint-sms-voice-v2 describe-registration-field-definitions --registration-type US_TOLL_FREE_REGISTRATIONThe following is partial output from the command:
{
"RegistrationFieldDefinitions": [
{
"SectionPath": "companyInfo",
"FieldPath": "companyInfo.companyName",
"FieldType": "TEXT",
"FieldRequirement": "REQUIRED",
"TextValidation": {
"MinLength": 1,
"MaxLength": 100,
"Pattern": "^(?=\\s*\\S)[\\s\\S]+$"
},
"DisplayHints": {
"Title": "Company name",
"ShortDescription": "Legal name which your company is registered under.",
"ExampleTextValue": "Example Corp"
}
},
...Depending on the registration you may be required to complete and attach a Letter of Authorization (LOA), opt-in workflow, or another type of required document. Check the individual registration for details and to download any forms.
Use the create-registration-attachment command to create the registration attachment. You can either upload the file to an Amazon S3 bucket and use the url or attach the document as part of the command. Use either AttachmentUrl or AttachmentBody, if both are specified then an exception is returned. The maximum file size is 500KB and valid file extensions are PDF, JPEG, and PNG.
The following example shows how to create the registration attachment and use the AttachmentUrl parameter.
$ aws pinpoint-sms-voice-v2 create-registration-attachment --attachment-url s3://BucketName/FileNameOn successful completion the command returns a RegistrationAttachmentID which is needed for other commands.
For more information on Amazon S3 commands such as creating a bucket or uploading a file, see Use high-level (s3) commands with the AWS CLI.
Next you need to add values for all of the required fields returned from the Get the field definitions step, this includes any attachments that you created. We recommend that you also complete any optional fields where applicable to your use case. A field is required or optional depending on the FieldRequirement value. Use the put-registration-field-value command to set the field values.
The following examples show to add a value for the company name or text value.
$aws pinpoint-sms-voice-v2 put-registration-field-value --registration-idRegID--field-pathcompanyInfo.companyName--text-valueAnyCompanyIn the preceding command replace the following:
-
Replace
RegIDwith the registration id returned from the Create a registration step. -
Replace
AnyCompanywith you company's name.
-
The following examples show to add a value for a select field.
$aws pinpoint-sms-voice-v2 put-registration-field-value --registration-idRegID--field-pathmessagingUseCase.monthlyMessageVolume--text-choicesSelectValueIn the preceding command replace the following:
-
Replace
RegIDwith the registration id returned from the Create a registration step. -
Replace
SelectValuewith one of the option values for the field.Use the describe-registration-field-definitions command to get the options for just one field:
aws pinpoint-sms-voice-v2 describe-registration-field-definitions --registration-type US_TOLL_FREE_REGISTRATION --field-pathsmessagingUseCase.monthlyMessageVolume{ "RegistrationFieldDefinitions": [ { "SectionPath": "messagingUseCase", "FieldPath": "messagingUseCase.monthlyMessageVolume", "FieldType": "SELECT", "FieldRequirement": "REQUIRED", "SelectValidation": { "MinChoices": 1, "MaxChoices": 1, "Options": [ "10", "100", "1,000", "10,000", "100,000", "250,000", "500,000", "750,000", "1,000,000", "5,000,000", "10,000,000+" ] }, "DisplayHints": { "Title": "Monthly SMS volume", "ShortDescription": "Estimated number of SMS messages which will be sent from this toll-free number each month." } } ], "RegistrationType": "US_TOLL_FREE_REGISTRATION" }
-
-
The following examples show how to add an attachment.
$aws pinpoint-sms-voice-v2 put-registration-field-value --registration-idRegID--field-pathmessagingUseCase.optInImage--registration-attachment-idRegistrationAttachmentIDIn the preceding command replace the following:
-
Replace
RegIDwith the registration id returned from the Create a registration step. -
Replace
RegistrationAttachmentIDwith the registration attachment id returned from the Create attachments step.
-
Note
Once you purchase an origination identity you are charged for it regardless of
registration status, see AWS End User
Messaging Pricing
If the registration's AssociationBehavior is
ASSOCIATE_AFTER_COMPLETE then you do not need to purchase or
associate the origination identity until after the registration has been
submitted and approved.
Now you need to request an origination identity which will later be associated with the registration. This example shows how to use the request-phone-number command to request a toll-free phone number through the AWS CLI. Use the request-sender-id to request a sender ID.
$ aws pinpoint-sms-voice-v2 request-phone-number --iso-country-code US --message-type TRANSACTIONAL --number-capabilities SMS --number-type TOLL_FREEOn successful completion the command returns the phone number unique identifier which is needed to associate the phone number with the registration.
Note
If the registration's AssociationBehavior is
ASSOCIATE_AFTER_COMPLETE then you do not need to purchase or
associate the origination identity until after the registration has been
submitted and approved.
To associate an origination identity to the registration use the create-registration-association AWS CLI command.
$ aws pinpoint-sms-voice-v2 create-registration-association --registration-id RegID --resource-id PhoneNumberIDIn the preceding command replace the following:
-
Replace
RegIDwith the registration id returned from the Create a registration step. -
Replace
PhoneNumberIDwith the phone number id returned from the Request an origination identity step.
Note
This command is used to associate any applicable resource with the registration. For example, it can be used to associate a 10DLC campaign registration with a 10DLC brand registration.
Once you submit your registration you will not be able to make any changes to it. Review you registration to make sure that all of your data is correct before submitting it.
Important
Once you submit your registration you can not make any changes to the registration or disassociated any resources from the registration until after it has been reviewed by a third party and returned back to you.
To submit a registration with the AWS CLI use the submit-registration-version command.
$ aws pinpoint-sms-voice-v2 submit-registration-version --registration-id RegIDIn the preceding command replace the following:
-
Replace
RegIDwith the registration id returned from the Create a registration step.
Once your registration has been submitted you can check its status using the describe-registrations command or console.
If the registration's AssociationBehavior is
ASSOCIATE_AFTER_COMPLETE you can purchase an origination identity
and associate it with the registration, once the registration's status is set to
COMPLETE.
If your registration's status is changed to REQUIRES_UPDATES then you can find and edit the flagged fields and resubmit the registration. For a list of registration rejection reasons, see Help with registration rejections. If you require help from Support with your registration rejection you can open a ticket.
