# What is AWS End User Messaging Notify? AWS End User Messaging Notify is a templated messaging feature that enables you to send SMS and voice messages using AWS-managed identities and pre-approved templates. With Notify, you can start sending code verification messages in minutes without provisioning phone numbers, managing sender IDs, or navigating carrier registration processes. **Note** Notify is a feature of AWS End User Messaging SMS and uses the `pinpoint-sms-voice-v2` API namespace. For general information about AWS End User Messaging SMS, see [What is AWS End User Messaging SMS?](what-is-sms-mms.md). **Key benefits** Notify provides instant messaging access with no phone number provisioning or carrier registration wait times. AWS manages phone number pools, sender IDs, and carrier integrations on your behalf. Pre-approved code verification templates are provided with multi-language support built in. Mandatory SMS Protect integration filters artificially inflated traffic (AIT) and SMS pumping attacks. You can send messages with a single API call using your configuration ID, destination number, and template variables. **How Notify works** Sending a message with Notify involves these steps: (1) Create a Notify configuration with your brand's display name, use case, and channels. AWS automatically validates your account, configures fraud protection, assigns templates, and sets tier-appropriate limits. (2) Browse pre-approved templates using `DescribeNotifyTemplates` to find templates for your tier, channel, and language. (3) Send messages using `SendNotifyTextMessage` or `SendNotifyVoiceMessage` with your configuration ID, destination phone number, and template variables. AWS selects the appropriate identity, resolves the template, and delivers the message. (4) Receive delivery receipts and status updates through your configured event destinations. (5) Optionally call `PutMessageFeedback` to report whether the end user successfully received and used the verification code. **Note** Before sending messages with Notify, ensure you have met the mobile carrier prerequisites for terms, privacy, and opt-in. For more information, see [Notify mobile carrier prerequisites](notify-compliance.md). **Notify vs. standard SMS sending** Use Notify when you need to send OTP or verification codes and want AWS to manage identities, routing, and compliance. Use standard AWS End User Messaging SMS sending (`SendTextMessage`, `SendVoiceMessage`) when you need custom message bodies, marketing or promotional messages, MMS messaging, or full control over which origination identity sends each message. **Notify vs. standard SMS sending** | Feature | Standard SMS | Notify | | --- | --- | --- | | Phone number provisioning | Required | Not required | | Number registration | Customer responsibility | AWS-managed | | Time to first message | Days to weeks | Minutes | | Message templates | Customer-managed | Pre-approved, AWS-managed | | Fraud protection | Optional | Mandatory | | Identity management | Customer-managed | AWS-managed | | Routing logic | Customer-managed | AWS-managed | **Key concepts** A *Notify configuration* is the primary resource representing your brand identity and messaging settings, including your display name, use case, enabled channels, enabled countries, and tier. Notify offers two service *tiers*: Basic tier provides immediate access with conservative limits, and Advanced tier unlocks higher limits and premium identities after brand verification. *Templates* are pre-approved message templates for code verification with multi-language support and typed variable substitution. Notify supports SMS and VOICE *channels*. *AWS-managed identities* are shared pools of phone numbers maintained by AWS across regions that Notify automatically selects based on destination country and channel. Each Notify configuration has a service-managed *Protect configuration* that enforces country-level restrictions and artificially inflated traffic filtering, managed by AWS and not modifiable by customers. **Accessing Notify** You can use Notify through the AWS End User Messaging SMS console, the AWS CLI, or the AWS SDKs. For information about accessing the console, see [Accessing AWS End User Messaging SMS](what-is-sms-mms.md#acessing-servicename). **Pricing** Notify pricing includes a per-message Notify service fee and standard SMS or voice transport rates based on destination country. For pricing details, see [AWS End User Messaging Pricing](https://aws.amazon.com//end-user-messaging/pricing/). **Regional availability** Notify is available in the same AWS Regions as AWS End User Messaging SMS. For a list of supported Regions, see [Regional availability](what-is-sms-mms.md#sms-regions). **Topics** + [Getting started with Notify](notify-getting-started.md) + [Managing Notify configurations](notify-configurations.md) + [Working with Notify templates](notify-templates.md) + [Notify tiers](notify-tiers.md) + [Sending messages with Notify](notify-send-messages.md) + [Using dedicated numbers with Notify](notify-dedicated-numbers.md) + [Notify supported countries](notify-countries.md) + [Notify spend limits](notify-spend-limits.md) + [Notify quotas and limits](notify-quotas.md) + [Notify mobile carrier prerequisites](notify-compliance.md) # Getting started with Notify This tutorial walks you through creating a Notify configuration and sending your first OTP message. You can complete this tutorial in about 5 minutes. ## Prerequisites + An AWS account. + IAM permissions for AWS End User Messaging SMS operations. For more information, see [Identity and access management for AWS End User Messaging SMS](security-iam.md). The following IAM policy grants permissions to send messages and browse templates: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sms-voice:SendNotifyTextMessage", "sms-voice:SendNotifyVoiceMessage", "sms-voice:DescribeNotifyTemplates", "sms-voice:DescribeNotifyConfigurations", "sms-voice:ListNotifyCountries", "sms-voice:PutMessageFeedback" ], "Resource": "*" } ] } ``` The following policy grants full Notify management permissions: ``` { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sms-voice:CreateNotifyConfiguration", "sms-voice:UpdateNotifyConfiguration", "sms-voice:DeleteNotifyConfiguration", "sms-voice:DescribeNotifyConfigurations", "sms-voice:DescribeNotifyTemplates", "sms-voice:ListNotifyCountries", "sms-voice:SendNotifyTextMessage", "sms-voice:SendNotifyVoiceMessage", "sms-voice:SetNotifyMessageSpendLimitOverride", "sms-voice:DeleteNotifyMessageSpendLimitOverride", "sms-voice:PutMessageFeedback" ], "Resource": "*" } ] } ``` To restrict permissions to a specific Notify configuration, use the configuration ARN for resource-level actions (such as `SendNotifyTextMessage`, `SendNotifyVoiceMessage`, `DescribeNotifyConfigurations`, `CreateNotifyConfiguration`, `UpdateNotifyConfiguration`, and `DeleteNotifyConfiguration`). Actions that do not support resource-level permissions (such as `DescribeNotifyTemplates`, `ListNotifyCountries`, `SetNotifyMessageSpendLimitOverride`, `DeleteNotifyMessageSpendLimitOverride`, and `PutMessageFeedback`) require `"Resource": "*"`. ## Step 1: Create a Notify configuration ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Notify**, choose **Notify configurations**. 1. Choose **Create Notify configuration**. 1. For **Display name**, enter your brand name (for example, `AcmeCorp`). 1. For **Use case**, **Code verification** is automatically selected. 1. For **Channels**, select **SMS**, **VOICE**, or both. 1. (Optional) Expand **Advanced settings** to select countries, a default template, an associated pool, or enable deletion protection. 1. Choose **Create Notify configuration**. Your configuration is created in **Pending** status while the system validates your account. Once validated, the status changes to **Active** and you can start sending messages. **Note** Configuration creation includes automated account validation and brand name checks. Most configurations are activated within seconds. If your brand name requires verification, the status will be **Requires verification**. ------ #### [ AWS CLI ] ``` aws pinpoint-sms-voice-v2 create-notify-configuration \ --display-name "AcmeCorp" \ --use-case CODE_VERIFICATION \ --enabled-channels SMS ``` ------ Configuration statuses: PENDING Configuration is being validated. ACTIVE Ready to send messages. REQUIRES\$1VERIFICATION Brand name requires verification before activation. REJECTED Configuration was rejected. Check `RejectionReason` for details. ## Step 2: Browse available templates Before sending, check which templates are available for your tier and channel: ``` aws pinpoint-sms-voice-v2 describe-notify-templates \ --filters '[{"Name":"channels","Values":["SMS"]},{"Name":"tier-access","Values":["BASIC"]}]' ``` ## Step 3: Send a test message ------ #### [ Console ] 1. In the Notify configurations list, choose your configuration. 1. Choose the **Test** tab. 1. Select a template from the templates table. 1. For **Destination phone number**, enter a phone number in E.164 format (for example, `+12065550100`). 1. Fill in the template variables (for example, enter `123456` for the **code** variable). 1. Choose **Send**. ------ #### [ AWS CLI ] ``` aws pinpoint-sms-voice-v2 send-notify-text-message \ --notify-configuration-id "nc-1234567890abcdef0" \ --destination-phone-number "+12065550100" \ --template-id "notify-code-verification-english-001" \ --template-variables '{"code":"123456"}' ``` ------ #### [ Python (boto3) ] ``` import boto3 client = boto3.client('pinpoint-sms-voice-v2') response = client.send_notify_text_message( NotifyConfigurationId='nc-1234567890abcdef0', DestinationPhoneNumber='+12065550100', TemplateId='notify-code-verification-english-001', TemplateVariables={ 'code': '123456' } ) print(f"Message ID: {response['MessageId']}") print(f"Resolved body: {response['ResolvedMessageBody']}") ``` ------ ## Step 4: Check available countries Use `ListNotifyCountries` to see which countries are available for your tier and channel: ``` aws pinpoint-sms-voice-v2 list-notify-countries \ --channels SMS \ --tier BASIC ``` ## Next steps + [Managing Notify configurations](notify-configurations.md) – Learn about all configuration options. + [Working with Notify templates](notify-templates.md) – Browse and understand available templates. + [Notify tiers](notify-tiers.md) – Learn about tiers and how to upgrade to Advanced. + [Notify spend limits](notify-spend-limits.md) – Manage your Notify spend limits. # Managing Notify configurations A Notify configuration is the central resource for Notify. It defines your display name, use case, enabled channels, enabled countries, and optional settings like a default template and associated phone pool. ## Configuration properties Display name A name that identifies your brand. Alphanumeric characters, underscores, hyphens, and spaces are allowed. Maximum 15 characters. When you submit a display name, it is automatically reviewed for profanity, URLs, and other disallowed content. See [Display name review](#notify-configurations-brand-review). Use case The messaging use case. Currently, `CODE_VERIFICATION` is supported. Enabled channels The channels available for sending: `SMS`, `VOICE`, or both. Enabled countries The countries you can send messages to. Available countries depend on your tier. See [Notify supported countries](notify-countries.md). Default template (Optional) A template used when you send a message without specifying a template ID. Associated pool (Optional) A phone pool containing your own origination identities. See [Using dedicated numbers with Notify](notify-dedicated-numbers.md). Tier `BASIC` (default) or `ADVANCED`. See [Upgrading to Advanced tier](notify-tiers.md#notify-tier-upgrade). Status The current status: `PENDING`, `ACTIVE`, `REJECTED`, or `REQUIRES_VERIFICATION`. You can send messages only when the status is `ACTIVE`. Deletion protection When enabled, the configuration cannot be deleted until deletion protection is disabled. Tags Key-value pairs for organizing and tracking your configurations. Maximum 50 tags per configuration. ## Display name review When you create a Notify configuration, your display name is automatically reviewed for profanity, URLs, and other disallowed content. This review uses [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/what-is-bedrock.html), an AWS AI service, to evaluate the submitted display name. If your display name is rejected, the configuration status is set to `REJECTED` and the `RejectionReason` field provides details. If you believe the rejection was made in error, you can create a support case in the [AWS Support Center](https://console.aws.amazon.com/support/home) to appeal the decision. **Using a display name owned by another organization** If you are sending messages on behalf of another organization and want to use their brand name as your display name, you must provide a letter of authorization (LOA) from the brand owner. Download the [brand verification LOA template](samples/Notify_Brand_Verification_LetterOfAuthorization.zip), have the brand owner complete and sign it, and attach it to your support case or registration. The LOA must be dated within the last 30 days. **Opting out of AI-assisted review** If you prefer not to have your display name evaluated via AI-assisted review, you can create a support case in the AWS Support Center and request that a Notify configuration be created manually on your behalf instead. ## Creating a Notify configuration ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Notify**, choose **Notify configurations**. 1. Choose **Create Notify configuration**. 1. For **Display name**, enter a name for your brand. 1. For **Use case**, choose **CODE\$1VERIFICATION**. 1. Select the channels to enable (**SMS**, **VOICE**, or both). 1. (Optional) Expand **Advanced settings** to select countries, a default template, an associated pool, or enable deletion protection. 1. (Optional) Expand **Tags** to add tags. 1. Choose **Create Notify configuration**. ------ #### [ AWS CLI ] Use the `create-notify-configuration` command: ``` aws pinpoint-sms-voice-v2 create-notify-configuration \ --display-name "MyBrand" \ --use-case CODE_VERIFICATION \ --enabled-channels SMS VOICE \ --enabled-countries US CA GB \ --tags Key=Environment,Value=Production ``` ------ ## Viewing Notify configurations ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, under **Notify**, choose **Notify configurations**. 1. Use the property filter to filter by display name, status, tier, or other properties. 1. Choose a configuration's display name to view its details. ------ #### [ AWS CLI ] List all configurations: ``` aws pinpoint-sms-voice-v2 describe-notify-configurations ``` Describe a specific configuration: ``` aws pinpoint-sms-voice-v2 describe-notify-configurations \ --notify-configuration-ids nc-1234567890abcdef0 ``` Filter by status: ``` aws pinpoint-sms-voice-v2 describe-notify-configurations \ --filters Name=status,Values=ACTIVE ``` ------ ## Updating a Notify configuration You can update the enabled channels, enabled countries, default template, associated pool, and deletion protection settings. ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to the Notify configuration you want to update. 1. Choose **Edit** to update channels, or use the individual tabs (Countries, Templates, Use Dedicated Numbers, Deletion protection) to update specific settings. 1. Make your changes and choose **Save**. ------ #### [ AWS CLI ] Update enabled countries: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --enabled-countries US CA GB DE FR ``` Set a default template: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --default-template-id notify-code-verification-english-001 ``` Clear the default template: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --default-template-id UNSET_DEFAULT_TEMPLATE ``` Associate a pool: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --pool-id pool-1234567890abcdef0 ``` Disassociate a pool: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --pool-id UNSET_DEFAULT_POOL_FOR_NOTIFY ``` Enable deletion protection: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --deletion-protection-enabled ``` ------ ## Deleting a Notify configuration **Note** If deletion protection is enabled, you must disable it before you can delete the configuration. ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to **Notify configurations**. 1. Select the configuration you want to delete. 1. Choose **Delete**. 1. Type `delete` in the confirmation field and choose **Delete**. ------ #### [ AWS CLI ] ``` aws pinpoint-sms-voice-v2 delete-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 ``` ------ # Working with Notify templates Notify templates are pre-approved, AWS-managed message templates for sending OTP and verification messages. Templates are pre-validated across supported countries. You select from available templates but cannot create or modify them. ## Template properties Template ID A unique identifier for the template. Template type The use case category. Currently, `CODE_VERIFICATION` is available. Channels The channels the template supports: `SMS`, `VOICE`, or both. Language code The language of the template content (for example, `en`, `es`, `fr`). Supported countries The countries where this template can be used. Tier access Which tiers can use this template (`BASIC`, `ADVANCED`, or both). Variables Placeholders in the template content that you provide values for at send time. Each variable has a name, type, and constraints. Variables with a source of `CUSTOMER` must be provided by you. Variables with a source of `SYSTEM` are populated automatically. Content The message body with `{{variable}}` placeholders. ## Browsing templates ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to a Notify configuration and choose the **Templates** tab. 1. The **All templates** section shows all available templates. Use the property filter to filter by supported countries, language code, or other properties. ------ #### [ AWS CLI ] List all templates: ``` aws pinpoint-sms-voice-v2 describe-notify-templates ``` Filter by template type: ``` aws pinpoint-sms-voice-v2 describe-notify-templates \ --filters Name=template-type,Values=CODE_VERIFICATION ``` Filter by channel: ``` aws pinpoint-sms-voice-v2 describe-notify-templates \ --filters Name=channels,Values=SMS ``` Filter by country: ``` aws pinpoint-sms-voice-v2 describe-notify-templates \ --filters Name=supported-countries,Values=US ``` Filter by language: ``` aws pinpoint-sms-voice-v2 describe-notify-templates \ --filters Name=language-code,Values=en ``` ------ ## Template variables Template variables are placeholders in the message content that are replaced with values you provide when sending a message. Each variable has the following metadata: + **Type** – The logical data type: `STRING`, `INTEGER`, or `BOOLEAN`. All values are passed as strings in the API, regardless of type. For example, pass an integer value as `"42"` and a boolean as `"true"`. + **Required** – Whether the variable must be provided. Required variables without a default value cause an error if omitted. + **Source** – Either `CUSTOMER` (you provide the value) or `SYSTEM` (automatically populated). + **Constraints** – Validation rules such as maximum length, minimum/maximum value, or a regex pattern. ## Setting a default template You can set a default template on a Notify configuration. When you send a message without specifying a template ID, the default template is used. If no default template is set and no template ID is provided in the send request, the request fails. To set or change the default template, see [Managing Notify configurations](notify-configurations.md). # Notify tiers Notify offers two service tiers with different capabilities and limits. All new configurations start on the Basic tier. You can upgrade to the Advanced tier after completing tier upgrade verification. ## Basic tier Basic tier provides immediate access to Notify with conservative limits designed for getting started and low-volume use cases. **Basic tier capabilities** | Capability | Basic tier | | --- | --- | | Access | Immediate after configuration creation | | Daily message limit | 200 messages | | Transactions per second (TPS) | 1 TPS | | Supported countries | 30 pre-approved low-risk countries | | Identity types | Long codes, toll-free, sender IDs | | SMS Protect | Mandatory (cannot be disabled) | | Country configuration | Fixed (pre-approved list only) | | Default spend limit | See [Notify spend limits](notify-spend-limits.md) | | Customer-owned identity support | Yes (optional pool association) | ## Advanced tier Advanced tier unlocks higher limits, premium identities, and configurable country rules after tier upgrade verification. **Advanced tier capabilities** | Capability | Advanced tier | | --- | --- | | Access | After tier upgrade verification | | Daily message limit | Unlimited | | Transactions per second (TPS) | 25 | | Supported countries | All supported countries | | Identity types | Short codes, long codes, toll-free, sender IDs | | SMS Protect | Mandatory | | Country configuration | Configurable allow/block rules | | Default spend limit | See [Notify spend limits](notify-spend-limits.md) | | Customer-owned identity support | Yes (optional pool association) | ## Upgrading to Advanced tier To upgrade from Basic to Advanced tier, you must complete tier upgrade verification by demonstrating that you have a legitimate end-user consent mechanism in place. ### What you need to provide Opt-in method Select how you collect consent from your end users: + **Verbal** – Consent collected via phone call (for example, customer service call or IVR confirmation). + **Digital form** – Consent collected via digital interaction (for example, web signup form, mobile app account creation, checkout checkbox, or terms acceptance). Proof of opt-in Provide evidence of your consent collection process: + For verbal opt-in: Call script or IVR flow showing where consent is obtained. + For digital opt-in: Screenshot or URL of the form or page where users give consent. Business documentation Provide information about your business and use case. **Important** Your opt-in process must include links to your terms and conditions and privacy policy pages. For the required language and examples, see [Notify mobile carrier prerequisites](notify-compliance.md). ### Opt-in examples **Verbal opt-in (IVR or customer service call)** "To verify your identity, we'll send a one-time verification code to your mobile phone. By providing your phone number, you consent to receive this automated text message. Message and data rates may apply. Message frequency varies. Reply HELP for help or STOP to cancel. Do you consent to receive this verification code?" **Digital form opt-in (web or mobile app)** "By entering my phone number and clicking 'Send Code,' I consent to receive an automated one-time verification code from [Your Brand] at the number provided. Message and data rates may apply. Message frequency varies. Reply HELP for help, STOP to cancel. Terms of use \$1 Privacy policy" **Note** These examples follow CTIA Messaging Principles and Best Practices for informational messaging. OTP verification codes are considered informational (not promotional) because the user initiates the request. While STOP/HELP disclosures are technically optional for single transactional messages, including them is recommended for carrier compliance, especially when using US short codes. ### How to request an upgrade ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. In the navigation pane, choose **Notify configurations**. 1. Select your configuration and choose the **Tier upgrade** tab. 1. Choose **Upgrade to Advanced**. 1. Complete the brand verification form with your opt-in method and proof. 1. Submit the request. ------ #### [ AWS CLI ] The tier upgrade process uses the existing registration system: 1. Create a brand verification registration: ``` aws pinpoint-sms-voice-v2 create-registration \ --registration-type MANAGED_ROUTES_BRAND_VERIFICATION ``` 2. Complete the registration fields using `put-registration-field-value`. 3. Submit the registration: ``` aws pinpoint-sms-voice-v2 submit-registration-version \ --registration-id reg-1234567890abcdef0 ``` Upon approval, the Notify configuration tier is automatically upgraded. ------ ### Review process Upgrade requests are reviewed using a combination of automated processing and human review. Reviewers validate that your opt-in mechanism is genuine, end users are clearly consenting to receive messages, and your use case aligns with code verification messaging. Most requests are processed within 3–5 business days. **Upgrade review outcomes** | Outcome | Description | | --- | --- | | Approved | Your configuration is upgraded to Advanced tier. | | More information needed | Additional documentation is required. You'll receive details on what's needed. | | Rejected | The request did not meet verification requirements. You can resubmit with updated information. | ### Tracking upgrade status The `TierUpgradeStatus` field on your Notify configuration shows the current status: **TierUpgradeStatus values** | Status | Description | | --- | --- | | BASIC | No upgrade has been requested. The configuration is at Basic tier. | | PENDING\$1UPGRADE | An upgrade request has been submitted and is under review. | | ADVANCED | The upgrade was approved. The configuration is at Advanced tier. | | REJECTED | The upgrade request was rejected. You can submit a new registration with corrected information. | ## Your compliance responsibilities Regardless of tier, you are responsible for: + **Obtaining consent** – Get appropriate consent from recipients before sending messages. For code verification, this typically means the user initiated the action that triggers the OTP (for example, logging in, creating an account, or resetting a password). + **Complying with applicable laws** – Follow legal requirements for your use case and destination countries, including the Telephone Consumer Protection Act (TCPA) in the US, GDPR in the EU, and other applicable regulations. + **Following carrier policies** – Comply with carrier policies that apply to your messaging. AWS will make reasonable efforts to notify you of changes to carrier policies. For more information, see [Notify mobile carrier prerequisites](notify-compliance.md). # Sending messages with Notify Notify provides two APIs for sending messages: + `SendNotifyTextMessage` – Sends an SMS message using a pre-approved template. + `SendNotifyVoiceMessage` – Sends a voice call that reads the template content using text-to-speech. ## Sending an SMS message ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to a Notify configuration and choose the **Test** tab. 1. For channel, select **Text**. 1. Select a template from the templates table. 1. Enter the destination phone number in E.164 format. 1. Fill in the template variables. 1. Choose **Send**. ------ #### [ AWS CLI ] ``` aws pinpoint-sms-voice-v2 send-notify-text-message \ --notify-configuration-id nc-1234567890abcdef0 \ --destination-phone-number +12065550100 \ --template-id notify-code-verification-english-001 \ --template-variables '{"code":"123456"}' ``` ------ #### [ Python (boto3) ] ``` import boto3 client = boto3.client('pinpoint-sms-voice-v2') response = client.send_notify_text_message( NotifyConfigurationId='nc-1234567890abcdef0', DestinationPhoneNumber='+12065550100', TemplateId='notify-code-verification-english-001', TemplateVariables={ 'code': '123456' } ) print(f"Message sent. MessageId: {response['MessageId']}") print(f"Resolved body: {response.get('ResolvedMessageBody')}") ``` ------ ## Sending a voice message Voice messages require the `VOICE` channel to be enabled on your Notify configuration. **Tip** For voice messages, separate digits with periods or spaces (for example, `"1. 2. 3. 4. 5. 6."`) so that the text-to-speech engine reads each digit individually instead of as a single number. ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to a Notify configuration and choose the **Test** tab. 1. For channel, select **Voice**. 1. Select a voice template from the templates table. 1. Enter the destination phone number and fill in template variables. 1. Choose **Send**. ------ #### [ AWS CLI ] ``` aws pinpoint-sms-voice-v2 send-notify-voice-message \ --notify-configuration-id nc-1234567890abcdef0 \ --destination-phone-number +12065550100 \ --template-id notify-code-verification-english-001 \ --template-variables '{"code":"123456"}' \ --voice-id JOANNA ``` ------ ## Using DryRun mode Set `DryRun` to `true` to validate a send request without actually delivering the message. DryRun mode checks template variable validation, country restrictions, and spend limits, but does not send the message or deduct from your spend limit. ``` aws pinpoint-sms-voice-v2 send-notify-text-message \ --notify-configuration-id nc-1234567890abcdef0 \ --destination-phone-number +12065550100 \ --template-id notify-code-verification-english-001 \ --template-variables '{"code":"123456"}' \ --dry-run ``` ## Send request parameters Both `SendNotifyTextMessage` and `SendNotifyVoiceMessage` accept the following parameters: NotifyConfigurationId (required) The ID or ARN of the Notify configuration. DestinationPhoneNumber (required) The recipient's phone number in E.164 format. TemplateVariables (required) A map of variable names to values. All values are strings, even for integer or boolean variables. TemplateId The template to use. If omitted, the configuration's default template is used. ConfigurationSetName A configuration set for event routing. Context Key-value pairs included in event records. DryRun Validates the request without sending. TimeToLive How long the message is valid, in seconds. Default is 72 hours. MessageFeedbackEnabled Enables message feedback tracking via the `PutMessageFeedback` API. VoiceId (voice only) The Amazon Polly voice to use (for example, `JOANNA`, `MATTHEW`). ## How message routing works AWS automatically selects the best origination identity for each message based on the destination country. If you have associated a phone pool with your Notify configuration, customer-owned identities in the pool are tried first. If no suitable customer-owned identity is available, AWS-managed identities are used as a fallback. ## Message feedback If you enable `MessageFeedbackEnabled` when sending a message, you can report whether the end user successfully received and used the code: ``` client.put_message_feedback( MessageId='msg-1234567890abcdef', MessageFeedbackStatus='RECEIVED' # or 'FAILED' ) ``` ## Delivery events Notify emits delivery events to your configured event destinations (CloudWatch, Amazon Data Firehose, or Amazon SNS). For information about setting up event destinations, see [Configuration sets in AWS End User Messaging SMS](configuration-sets.md). **Delivery event types** | Event | Description | | --- | --- | | PENDING | Message is queued for delivery. | | DELIVERED | Message was delivered to the recipient's device. | | FAILED | Message delivery failed. Check the failure reason for details. | | BLOCKED | Message was blocked by Protect configuration rules. | ## Error handling ValidationException Missing or invalid template variables, invalid phone number format, or destination country not enabled on the configuration. ResourceNotFoundException The Notify configuration or template was not found. ServiceQuotaExceededException Daily message limit (Basic tier) or monthly spend limit reached. ConflictException The Notify configuration is not in `ACTIVE` status. ## Important notes + **Two-way messaging** – Two-way messaging is not supported when using AWS-managed origination identities. If you need two-way messaging, associate your own phone pool. See [Using dedicated numbers with Notify](notify-dedicated-numbers.md). + **Opt-out behavior** – For OTP use cases with AWS-managed identities, STOP keyword responses are informational only. No persistent opt-out list is maintained because each OTP request is an implicit opt-in. If you associate your own phone pool, the pool's opt-out list is respected. ## Troubleshooting **Messages not delivering** If your messages are not being delivered, verify the following: 1. Verify the destination phone number is in E.164 format (starts with `+` and country code). 1. Check that the destination country is in your `EnabledCountries` list. 1. Verify your configuration status is `ACTIVE`. 1. Check your spend limit hasn't been exceeded. **BLOCKED status** The message was blocked by a Protect configuration. Common reasons include the destination country not being in your enabled countries list, or the message being flagged as potential AIT (artificially inflated traffic). **Validation errors** Ensure all required `TemplateVariables` are provided. Check that variable values match their declared types (for example, integers are valid numbers). Verify the template ID exists and is active. # Using dedicated numbers with Notify By default, Notify uses AWS-managed origination identities to send messages. You can optionally associate an existing phone pool with your Notify configuration to use your own dedicated phone numbers alongside AWS-managed identities. **Note** For some countries, AWS does not provide managed origination identities. In these cases, you must associate your own phone pool with customer-owned numbers to send messages to those countries. Use the `ListNotifyCountries` API or the console Countries tab to check which countries require customer-owned identities. ## How hybrid routing works When you associate a phone pool with a Notify configuration, the system uses the following routing logic for each message: 1. Check the associated pool for a customer-owned origination identity that supports the destination country. 1. If a matching identity is found, use it to send the message. 1. If no matching identity is found (or no pool is associated), fall back to AWS-managed identities. ## Benefits of associating a pool + Use your own dedicated short codes or toll-free numbers for specific countries. + Existing opt-out lists on the pool are respected. ## Managing pool association ------ #### [ Console ] **Associate a pool** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to a Notify configuration and choose the **Use Dedicated Numbers** tab. 1. Choose **Associate pool**. 1. Select a pool from the table and choose **Associate pool**. **Disassociate a pool** 1. On the **Use Dedicated Numbers** tab, choose **Disassociate pool**. 1. Type `confirm` in the confirmation field and choose **Disassociate pool**. ------ #### [ AWS CLI ] Associate a pool: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --pool-id pool-1234567890abcdef0 ``` Disassociate a pool: ``` aws pinpoint-sms-voice-v2 update-notify-configuration \ --notify-configuration-id nc-1234567890abcdef0 \ --pool-id UNSET_DEFAULT_POOL_FOR_NOTIFY ``` ------ **Note** The pool must exist in the same AWS account. You can change or remove the pool association at any time. # Notify supported countries The countries available for Notify messaging depend on your Notify configuration's tier: + **Basic tier** – A curated set of countries optimized for reliability and quality. + **Advanced tier** – An expanded list with additional countries. Some Advanced-tier countries may require you to associate your own phone pool with customer-owned origination identities. Country availability may change over time. Use the `ListNotifyCountries` API or the console to check the current list of supported countries. ## Basic tier countries Basic tier supports 30 pre-approved countries. Use the `ListNotifyCountries` API for the most current list. **Basic tier supported countries** | Country | ISO code | | --- | --- | | American Samoa | AS | | Australia | AU | | Belgium | BE | | Brazil | BR | | Canada | CA | | Colombia | CO | | Denmark | DK | | Finland | FI | | France | FR | | Germany | DE | | Guam | GU | | Hong Kong | HK | | India | IN | | Ireland | IE | | Italy | IT | | Japan | JP | | Mexico | MX | | Netherlands | NL | | New Zealand | NZ | | Northern Mariana Islands | MP | | Portugal | PT | | Puerto Rico | PR | | Singapore | SG | | South Korea | KR | | Spain | ES | | Sweden | SE | | Switzerland | CH | | United Kingdom | GB | | United States | US | | US Virgin Islands | VI | ## Advanced tier countries Advanced tier supports all countries available in AWS End User Messaging SMS. Use the `ListNotifyCountries` API with `--tier ADVANCED` to see the full list. ## Checking supported countries ------ #### [ Console ] 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to a Notify configuration and choose the **Countries** tab. 1. The table shows countries grouped by region. Countries that require the Advanced tier are marked with an indicator. Use the property filter to search by country name or region. ------ #### [ AWS CLI ] List all supported countries: ``` aws pinpoint-sms-voice-v2 list-notify-countries ``` Filter by channel: ``` aws pinpoint-sms-voice-v2 list-notify-countries \ --channels SMS ``` Filter by tier: ``` aws pinpoint-sms-voice-v2 list-notify-countries \ --tier BASIC ``` Filter by use case: ``` aws pinpoint-sms-voice-v2 list-notify-countries \ --use-cases CODE_VERIFICATION ``` ------ ## Country information fields The `ListNotifyCountries` response includes the following information for each country: IsoCountryCode The two-character ISO 3166-1 alpha-2 country code. CountryName The name of the country. SupportedChannels The channels available for this country (`SMS`, `VOICE`). SupportedUseCases The use cases available for this country. SupportedTiers The tiers that can send to this country (`BASIC`, `ADVANCED`, or both). CustomerOwnedIdentityRequired Whether you must associate your own phone pool with customer-owned origination identities to send to this country. If `true`, see [Using dedicated numbers with Notify](notify-dedicated-numbers.md). ## Enabling countries on a configuration To update the countries enabled on a Notify configuration, see [Managing Notify configurations](notify-configurations.md). **Note** If your configuration is on the Basic tier, countries that require the Advanced tier are visible but cannot be selected. Upgrade to the Advanced tier to access these countries. # Notify spend limits Notify has its own dedicated monthly spend limit, separate from your SMS, MMS, and voice spend limits. Sending messages via Notify does not count against your SMS or voice spend limits. The *account limit* is the maximum amount, in US dollars, that you can spend each month sending Notify messages. You can request an increase through the Service Quotas console. The *enforced limit* is an optional spending cap between \$11 and your account limit. When you reach the enforced limit, `SendNotifyTextMessage` and `SendNotifyVoiceMessage` return a `ServiceQuotaExceededException`. Your Notify spend limit reflects the combined cost of the messaging channel fee and the Notify service fee for each message sent. ## Managing Notify spend limits ------ #### [ Console ] **View spend limits** 1. Open the AWS End User Messaging SMS console at [https://console.aws.amazon.com/sms-voice/](https://console.aws.amazon.com/sms-voice/). 1. Navigate to a Notify configuration and choose the **Spend limit** tab. 1. The tab shows your max spend limit, enforced spend limit, current month spend, and remaining balance. **Edit the enforced limit** 1. On the **Spend limit** tab, choose **Edit settings**. 1. Choose **Update enforced spend limit** and enter a new value, or choose **Default to max** to remove the override. 1. Choose **Save changes**. ------ #### [ AWS CLI ] Set an enforced spend limit: ``` aws pinpoint-sms-voice-v2 set-notify-message-spend-limit-override \ --monthly-limit 100 ``` Remove the enforced limit (revert to account limit): ``` aws pinpoint-sms-voice-v2 delete-notify-message-spend-limit-override ``` View all spend limits (Notify appears alongside SMS and voice): ``` aws pinpoint-sms-voice-v2 describe-spend-limits ``` ------ ## Requesting a higher account limit To increase your Notify account spend limit beyond the default, use the Service Quotas console or create a support case. For more information, see [Quotas for AWS End User Messaging SMS](quotas.md). # Notify quotas and limits This section describes the default quotas, rate limits, and supported countries for Notify. ## Account-level quotas **Account-level quotas** | Quota | Default value | Adjustable | | --- | --- | --- | | Notify configurations per account | 25 | Yes | | Messages to a single destination phone number per day (account-wide) | 10 | No | ## Configuration-level limits **Configuration-level limits by tier** | Limit | Basic tier | Advanced tier | | --- | --- | --- | | Messages per day | 200 | Unlimited | | TPS per configuration | 1 | 25 | | Supported countries | 30 pre-approved | All supported\$1 | **Note** For a given destination phone number, the limit is 10 messages per day per notify configuration and 10 messages per day per account. \$1 Some countries require a customer-owned origination identity. Use the `ListNotifyCountries` API to check which countries require customer-owned identities. For more information, see [Notify supported countries](notify-countries.md). ## API rate limits **API rate limits** | API operation | Default RPS | | --- | --- | | CreateNotifyConfiguration | 1 | | UpdateNotifyConfiguration | 1 | | DeleteNotifyConfiguration | 1 | | DescribeNotifyConfigurations | 1 | | DescribeNotifyTemplates | 1 | | ListNotifyCountries | 1 | | SendNotifyTextMessage | 1 (Basic) / 25 (Advanced) | | SendNotifyVoiceMessage | 1 (Basic) / 25 (Advanced) | | SetNotifyMessageSpendLimitOverride | 1 | | DeleteNotifyMessageSpendLimitOverride | 1 | ## Requesting quota increases To request an increase to any Notify quota: 1. Open the [Service Quotas console](https://console.aws.amazon.com/servicequotas/). 1. Navigate to **AWS End User Messaging SMS**. 1. Select the quota you want to increase. 1. Choose **Request quota increase**. Alternatively, you can create a support case at the [AWS Support Center](https://console.aws.amazon.com/support/home). # Notify mobile carrier prerequisites When using AWS End User Messaging Notify, you are responsible for complying with applicable messaging laws and mobile carrier requirements in each country or region where your customers are located. Consult an attorney to assess compliance obligations. Non-compliance with these requirements may result in carrier audit and removal of your access to Notify. This page specifies mobile-carrier mandated prerequisites for using Notify, including the minimum required language you must make available to your customers detailing your terms and conditions, privacy policy, and opt-in flow applicable to your messaging. **Important** You must publish your own terms and conditions and privacy policy pages that include the required language described below. You must also implement an opt-in flow before sending messages through Notify. These requirements apply to both Basic and Advanced tiers. ## Required terms and conditions Mobile carriers require that you make a specific set of messaging terms and conditions available to your customers. Your terms and conditions page must include, at minimum, the following information. Replace the bracketed placeholders with your own values. ``` Subscribers will opt-in via [YOUR_WEBSITE_URL] to receive verification messages from [YOUR_COMPANY_NAME], powered by AWS Notify. Message frequency may vary per user. Text "HELP" for help. Text "STOP" to cancel. Message and data rates may apply for any messages sent to you from us and to us from you. Carriers are not liable for delayed or undelivered messages. If you have any questions about your text plan or data plan, contact your wireless provider. For all questions about the services provided, you can send an email to [YOUR_SUPPORT_EMAIL] or call [YOUR_SUPPORT_PHONE_NUMBER]. If you have questions regarding privacy, please read our privacy policy at [YOUR_PRIVACY_POLICY_URL]. ``` **Important** You must host this content at a publicly accessible URL and link to it from your opt-in flow. ## Required privacy policy Mobile carriers also require that you make a privacy policy available to your customers. Your privacy policy page must include, at minimum, the following statements: + No mobile numbers will be shared with third parties or affiliates for marketing or promotional purposes. + Text messaging originator opt-in data and consent will not be shared with any third parties. + Messages are delivered through AWS Notify. AWS does not share end user phone numbers with third parties for marketing or promotional purposes. **Important** You must host this content at a publicly accessible URL. Your terms and conditions page must link to your privacy policy, and your privacy policy must link to your terms and conditions. Your use of Notify is also governed by the [AWS Service Terms](https://aws.amazon.com/service-terms/), including Section 29 (Amazon Pinpoint and AWS End User Messaging). ## Required opt-in flow Before sending messages through Notify, mobile carriers require you to implement an opt-in flow that obtains explicit consent from your end users. The opt-in flow must meet the following requirements: + End users must actively consent to receive messages (for example, by selecting a checkbox, choosing a button, or providing verbal confirmation). + The opt-in must clearly state that the user will receive verification messages. + The opt-in must include the disclosures: "Message and data rates may apply. Message frequency varies. Reply HELP for help. Reply STOP to cancel." + The opt-in must include links to your terms and conditions and privacy policy. + You must maintain records of consent. **Digital opt-in example (web or mobile app)** The following is an example of a digital opt-in. Replace the bracketed placeholders with your own values. ``` ☐ By entering my phone number and clicking "Send Code," I consent to receive an automated one-time verification code from [YOUR_BRAND] at the number provided. Messages are powered by AWS Notify. Message and data rates may apply. Message frequency varies. Reply HELP for help, STOP to cancel. Terms and conditions: [YOUR_TERMS_URL] Privacy policy: [YOUR_PRIVACY_POLICY_URL] ``` **Verbal opt-in example (IVR or customer service call)** The following is an example of a verbal opt-in script. ``` "To verify your identity, we'll send a one-time verification code to your mobile phone, powered by AWS Notify. By providing your phone number, you consent to receive this automated text message. Message and data rates may apply. Message frequency varies. Reply HELP for help or STOP to cancel. Do you consent to receive this verification code?" ``` **Note** These examples follow CTIA Messaging Principles and Best Practices for informational messaging. OTP verification codes are considered informational (not promotional) because the user initiates the request. STOP/HELP disclosures are required for all messages sent through Notify. ## Customer support requirements You must provide your own customer support contact information (email address and/or phone number) in your terms and conditions. This support contact must be accessible without requiring a login. Carrier and regulatory guidelines require that end users can reach support for questions about the messages they receive. ## Notify mobile-carrier prerequisites checklist Before sending messages with Notify, verify that you have completed the following: + Published a terms and conditions page with the required language at a public URL. + Published a privacy policy page with the required statements at a public URL. + Implemented an opt-in flow that obtains explicit consent and includes all required disclosures. + Included links to your terms and privacy policy in your opt-in flow. + Provided a customer support contact (email and/or phone) that does not require a login. + Cross-linked your terms and privacy policy pages to each other.