Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/defending-against-sms-pumping-new-aws-features-to-help-combat-artificially-inflated-traffic/

As businesses increasingly rely on SMS messaging to engage customers, AWS End User Messaging is enhancing its SMS Protect feature to now include automated message filtering based on the risk of Artificially Inflated Traffic (AIT) from each message request. This new capability helps protect against AIT, also known as SMS pumping. AIT occurs when malicious actors use bots and other measures to generate fake SMS traffic, targeting businesses’ customer communication workflows like one-time password triggers, app downloads, and promotional signups. In a recent report co-authored by Enea it was shown that AIT accounted for 19.8 billion to 35.7 billion fraudulent SMS messages in 2023, costing over $1 billion. All workflows with user generated messages are susceptible to AIT but insecure public webforms are the most commonly used as a vector to exploit and generate SMS messages. The goal is to artificially inflate the number of SMS messages a business sends, resulting in increased costs and a negative impact on the sender’s reputation.

We launched AWS End User Messaging Protect to help our customers combat this growing threat. Initially launched with Country Level Blocking, we’ve now launched two new features, called Monitor and Filter, within AWS End User Messaging’s Protect capabilities. Updating your current security posture for SMS with Monitor and Filter, along with adhering to some other best practice security measures we will cover later, will make it harder for bad actors to target and inflate your SMS costs with bots or other measures.

What is SMS Protect Filter and Monitor?

Filter and Monitor are the next layers of defense in our Protect Feature Set. These features are designed to provide enhanced protection against AIT for countries in which you need to send messages by analyzing and proactively blocking messages that are suspected to be fraudulent. The Filter setting blocks suspected AIT messages. The Monitor mode allows you to evaluate how Filter would affect your sending, without blocking. Monitor could also be used for the events it emits, which could be leveraged in your own custom AIT solutions, but again, does not automatically block messages.

Filter Mode: Automated Blocking of Suspected Artificial Traffic

The Filter mode in Protect takes your AIT mitigation efforts to the next level by automatically blocking messages that exhibit patterns of artificial inflation. When you set your configuration to “Filter” the model will automatically filter any messages being sent that match patterns indicative of AIT.

Filter mode provides automated defense against AIT by analyzing and proactively blocking AIT messages before they leave AWS, reducing your exposure to the financial and reputational impacts of SMS pumping. Turning on Filter at the Account level is the quickest way to protecting yourself. The tutorial below will walk you through configuration.

Importantly, when a message is blocked in Filter mode, you do not incur the normal per-message fees, instead you only pay for the lesser costs associated with the Protect Filter capabilities, providing a more cost effective approach to message security.

Monitor Mode: Gain Visibility and Insights into Potentially Suspicious Traffic

The Monitor mode in Protect works identical to filter, it uses the same AIT prediction models behind the scenes, but rather than blocking suspected AIT it simply emits recommendations for blocking based on the patterns of data. The recommendations are delivered in a new field attached to the Delivery Receipts (DLRs) that are already streamed via Event Destinations. The recommendations are also logged in summary to CloudWatch and the End User Messaging Console Dashboards. This provides you with valuable data and insights to help inform your AIT mitigation strategy.

Messages sent while in monitor mode will not be blocked and will be charged the country per message cost as well as the Protect Monitor per message cost.

If you want to see what our AIT prediction models recommend without AWS actually blocking messages, you can start in Monitor Mode and change to Filter when you are more comfortable. This allows you to understand how your traffic is analyzed by our AIT prediction models without immediately blocking messages, offering a cautious and informed approach to how Filter will affect your Account.

The Monitor mode reports include detailed analytics on blocked message volumes, geographic distribution, carrier patterns, and more. By analyzing this data, you can identify specific countries, number ranges, or sending behaviors that may be indicative of artificially inflated traffic. This helps you make informed decisions about where to apply more stringent controls.

Importantly, during the monitoring phase, Protect also provides recommendations on whether a particular message would have been blocked and whether certain numbers should be blocked in the future. This gives you the ability to fine-tune your configurations and better understand your traffic before taking enforcement actions.

How do you get started with Protect Monitor and Filter?

Every customer’s needs are unique, but for most customers, we suggest the following steps:

1. Block all countries to which you do not send messages
   1. Your first line of defense should be to block all traffic to countries where you don’t conduct business or need to send messages. Preventing unwanted messages from being sent is the simplest way to help prevent SMS pumping in the first place. You can use Protect Country Blocking rules to do this and they can can be applied to SMS, MMS, and voice messages sent from your AWS account. For a tutorial on how to do this you can read this earlier blog on Protect.
2. Create an account level “Filter” configuration
   1. When considering the risk of AIT in a specific country we recommend aligning risk level with the SMS per message cost. The higher the cost the higher the risk.
3. Make sure that your forms and other vulnerable public facing messaging workflows are protected with best practice security measures that we will review further on in this post.

How to create a protect configuration

You can use a Protect configuration at different levels of granularity:

1. As the default for your entire AWS account(Good for customers with a single use case)
2. Associated with a specific Configuration Set
3. Directly specified when calling the SendMediaMessage, SendTextMessage, or SendVoiceMessage APIs
   NOTE: You can only change your MMS country rules list through the AWS End User Messaging SMS and voice v2 API or AWS CLI. The Voice rules can be changed in the console but only after creating an SMS Protect Configuration. Once you have created your first Configuration you can edit it and select the “Voice Rules” tab.

The main benefit of Protect configurations is the ability to control where you send messages and avoid unexpected costs or compliance issues. By creating multiple configurations you can apply specific rules that control how messages are processed and delivered based on your unique business needs. Let’s walk through how to set them up.

Creating a Protect Configuration

1. To create a Protect Configuration, log into the AWS Management Console and navigate to End User Messaging.
2. From there, go to the “SMS” section and select “Protect configurations”.
3. Click the “Create protect configuration” button and give your new configuration a name.
   1. Define the specific allow and block rules for SMS, MMS, and voice messages.
      1. Checking a box next to a country blocks that country and checking the box for a region will block all countries associated with that region.

Once you’ve configured the country rules, you can choose how to associate this Protect configuration:

1. Set it as the default for your entire AWS account
   1. For many customers this should be the default. Having an account level configuration as a fallback helps protect you incase you forget to specify a protect configuration in your request.
   2. Note: To use a protect configuration with other AWS services to send messages, like Amazon SNS, Amazon Connect, or Amazon Pinpoint, you need to set your protect configuration as the account default
2. Associate it with one or more Configuration Sets
   1. This setting will be applied anytime you send SMS with the config set associated with this Protect Configuration
3. Leave it unassociated to use it explicitly in API calls
   1. This setting allows you to apply it whenever you want. This will override any previous associations when you reference the “ProtectConfigurationId” in your SendMediaMessage, SendTextMessage, or SendVoiceMessage calls

You can also add optional tags to help organize your resources.

1. Click “Create protect configuration”
   1. NOTE: You can only change your MMS country rules list through the AWS End User Messaging SMS and voice v2 API or AWS CLI. The Voice rules can be changed in the console but only after creating an SMS Protect Configuration. Once you have created your first Configuration you can edit it and select the “Voice Rules” tab.
2. How to add Filter or Monitor to the Protect Configuration you just created
   1. Click into the Protect Configuration you just created
      1. Note the “SMS Rules” tab and the “Voice Rules” tab can have different rule settings. Make sure you are editing the right channel
3. You will once again select the country or region you wish to set to Filter(recommended) or Monitor

1. 1. Confirm the changes and you will see your changes in the next screen

Getting more granular with Protect Configurations

In most cases you should be using “Filter” account wide for the countries you are concerned about AIT in, but If you have different public and/or private messaging workflows you may benefit from a more precise, or granular, approach to your messaging and security practices. If you want more control, the first step is to identify your traffic that is a high risk for SMS pumping. Any public-facing forms or workflows that trigger SMS being sent are prime targets for attackers to try and pump SMS are at high risk, such as:

• One-time passwords or 2FA flows
• Password/User resets
• New user registrations
• Other

Creating a separate Protect Configuration for each of these different workflows will help the models in Protect more effectively identify anomalies and tailor its detection models to your specific messaging patterns. Service-initiated messages, such as appointment reminders or marketing campaigns that are not user-generated are at much less risk of SMS pumping attacks so you may decide not to include them in the same Protect config as a public facing workflow to reduce overall costs.

You can follow the directions above for creating a Protect Configuration for each of the workflows you identify. You might configure something like the below, where “OTP New Sign Up” and “Password Reset” have Filter enabled for the countries of concern and the “Marketing Newsletter” Configuration would not have either configured since that use case does not involve a publicly available form that triggers an SMS being sent. Creating a Protect Configuration for different use cases gives you more granular control over your messaging, your messaging budget, and ensuring the integrity of your communications

Updating an Existing Protect Configuration

After creating a Protect configuration, you may need to modify the country rules, change the association or as we saw above, add Filter or Monitor to certain countries. To do this, simply navigate back to the “Protect configurations” section and select the one you want to update.

From here you can edit the allow/block country lists, change the association, or even delete the configuration if needed. Just be careful with the account default – you’ll want to be sure you have another default in place before removing the existing one.

Using Protect Configurations

Once you have your Protect configurations set up, you can start putting them to use. If you’ve associated one with a Configuration Set, any messages sent using that Configuration Set will automatically have the Protect rules applied.

Alternatively, you can specify the ProtectConfigurationId parameter when calling the SendMediaMessage, SendTextMessage, or SendVoiceMessage APIs. This allows you to override the account default or Configuration Set association on a per-message basis.

Reporting on Protect Configurations

There are two places within the console that you can see metrics for your Protect Configurations. The Monitoring tab on a protect configuration provides an overview of message delivery metrics for the protect configuration. To view all metrics for your account in the AWS End User Messaging SMS console choose Dashboard in the left hand navigation. You can also use CloudWatch to view and create alarms. For more information on CloudWatch metrics, see Dashboard metrics, and Create CloudWatch Alarms.

Monitoring tab on a specific Protect Configuration

End User Messaging provides multiple charts that helps you understand how your country rule configurations (Allow, Block, Monitor, or Filter), along with phone number rule overrides are controlling SMS sending overall, and to specific countries.

The included charts are:

• Number and Percentage of Blocked Messages: Shows the count and percentage of SMS and MMS messages that were blocked during the selected time period. This includes messages blocked by country rules set to ‘block’ or ‘filter’ mode, as well as messages blocked by phone number override rules.
• Number of Blocked Messages by Country: Shows the count of SMS and MMS messages that were blocked during the selected time period, broken down by destination country.
• Number and Percentage of Messages Recommended to Block: Shows the count and percentage of SMS and MMS messages that were identified as risky by the AIT risk prediction model. This includes messages in both ‘monitor’ and ‘filter’ modes. In monitor mode, these messages are delivered but flagged; in filter mode, these messages are blocked.
• Number of Messages Recommended to Block by Country: Shows the count of SMS and MMS messages identified as risky by the AIT prediction model, broken down by destination country.

Implementing a Layered Approach to SMS Security

While Filter and Monitor are new tools in the fight against AIT, they should be implemented as part of a broader, layered security strategy for your SMS messaging infrastructure. Here are some best practices to consider:

Identify and compartmentalize Your Traffic

You are able to create multiple Protect Configurations based on different use cases, such as one-time passwords, marketing campaigns, and appointment reminders. This granular approach allows Protect’s prediction models to better understand your expected traffic patterns and identify anomalies more accurately. Once you have identified your traffic types you can assign different configurations to them. You may set a marketing configuration to not be filtered or monitored because it’s not user generated but an OTP type with a publicly available form you may want to set to Filter. In this way you save money by protecting only the messages that are more likely to be susceptible to AIT. Each of these may block the same countries but operate differently with regards to identifying and blocking potentially fraudulent traffic.

Leverage Geographic Controls:

Always start by blocking countries where you have no business presence, then allow-list the regions where you actively engage customers and have not seen AIT issues. For countries where you suspect potential abuse, utilize the Monitor mode to gather data before deciding on a blocking strategy.

Allow-list Legitimate phone numbers in countries you are blocking

To avoid impacting your critical messaging workflows, implement phone number rule overrides for specific countries where you are blocking traffic. As an example, if you have engineers in Columbia that you want to be able to send SMS to but you don’t have any legitimate reason other than that to send to Columbian handsets you can block Columbia but allow-list those engineer’s phone numbers. You can also provide your front end support teams the functionality to add numbers to allow-lists in case a number is mistakenly blocked by Filter recommendations

1. To create a phone number override rule using the console, follow these steps:
2. Open the AWS End User Messaging SMS console at https://console.aws.amazon.com/sms-voice/.
3. In the navigation pane, under Protect, choose the Protect configuration you want to add allow-list numbers in
4. Choose the Rule overrides tab and in the Rules override section choose Add override.
   1. In the Rule override details section, enter the following:
      1. For Destination phone number enter the phone number to create the rule for. The phone number must start with a ‘+’ and can’t contain any spaces, hyphens, or parentheses. For example, +1 (206) 555-0142 is not in the correct format, but +12065550142 is.
      2. For Override type choose either Always allow or Always block.
      3. For Expiration date – optional choose a date for the rule expire or leave it blank for the rule to never expire.
5. Choose Add rule override.

Integrate with Complementary Security Services

Enhance your SMS security posture by integrating Protect with other AWS services, such as AWS Web Application Firewall (WAF) for web-based attack protection and Amazon Cognito for robust user authentication. See this post on Cognito Security for more detailed information on how to add self-service sign-up, sign-in, and control access features to your web and mobile applications while benefitting from SMS authentication and fraud protection with End User Messaging Protect Block, Monitor, and Filter.

WAF has out of the box support for complementary security protections such as CAPTCHA, IP blocking, and JA3 fingerprint matching which are all best practice features to help protect your public forms that may be at risk for SMS pumping.

Review and Iterate

Regularly review your Protect configurations, analyze false positive rates, and update your allow-lists and rules as your messaging patterns evolve. If you are satisfied with your blocking, leave it alone. If you want to get more precise and remove false positives, look for which protect configurations have identified suspected AIT, and try to make them more granular. For example, if you have a sign-up form that is currently being triggered from two separate web pages, you could have a config set for each of those pages and trigger a different config set with Filter mode activated for each. Maintaining an agile, data-driven approach is key to ensuring optimal balance between security and service availability for your legitimate customers.

Conclusion

Take a proactive, multilayered approach to combating the growing threat of SMS fraud by leveraging the new Filter and Monitor capabilities within AWS End User Messaging Protect. These features empower you to gain visibility into potentially malicious traffic, automate the blocking of suspected AIT, and protect your messaging infrastructure while preserving the seamless experience your customers expect.

To get started with Protect and explore these new features, visit the AWS End User Messaging documentation or reach out to your AWS account team. We’re here to help you strengthen the security and integrity of your SMS communications.

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/automating-sender-id-configuration-for-sms-with-aws-end-user-messaging-apis/

Global SMS messaging with consistent Sender ID branding requires configuring the same Sender ID across multiple countries, which is a time-consuming process for businesses operating internationally. In this post, we’ll show you how to automate the configuration of Sender IDs for countries that do not have registration requirements using the AWS End User Messaging v2 API.

The Challenge of Multi-Country Sender ID Configuration

When sending SMS messages internationally, if you are using Sender ID, you want your brand to be consistently recognized. This means configuring the same Sender ID in each country you send to. However there are several challenges related to this:

• Each country must be done manually, one at a time, if using the AWS Console
• If you have multiple environments for testing the process must be repeated for each Account/Region
• If you are moving account/regions you have to reconfigure each country in the new Account/Region
• Manual configuration can be error prone
• Errors can be detrimental to a brand

The Solution: AWS Lambda Automation

This solution can be applied to any country that supports Sender ID configurations and does not require registration. You can view a comprehensive list of these eligible countries here.

Below is an AWS Lambda function that streamlines this process by handling bulk configuration requests. The function solves the challenges in handling multiple country configurations in a single automated workflow. Here’s the complete code:

import boto3
import uuid
import json
import time
from typing import Dict, Any, List

def validate_input(sender_id: str, countries: List[str]) -> bool:
    if not 1 <= len(sender_id) <= 11:
        raise ValueError("Sender ID must be between 1 and 11 characters")
    
    if not sender_id.replace('_', '').replace('-', '').isalnum():
        raise ValueError("Sender ID can only contain alphanumeric characters, underscore, and hyphen")
    
    if not countries:
        raise ValueError("At least one country code must be provided")
    
    return True

def request_sender_id(client, sender_id: str, countries: List[str], message_types: List[str] = None, tags: List[Dict] = None) -> List[Dict]:
    if message_types is None:
        message_types = ["TRANSACTIONAL", "PROMOTIONAL"]
    
    results = []
    
    for i, country in enumerate(countries):
        if i > 0:
            time.sleep(1)  # Rate limiting: 1 request per second
            
        try:
            print(f"Processing country: {country} ({i+1}/{len(countries)})")
            request_params = {
                'ClientToken': str(uuid.uuid4()),
                'SenderId': sender_id,
                'IsoCountryCode': country.upper(),
                'MessageTypes': message_types,
                'DeletionProtectionEnabled':True
            }
            
            if tags:
                request_params['Tags'] = tags
                
            response = client.request_sender_id(**request_params)
            
            results.append({
                'Country': country,
                'Status': 'Success',
                'SenderIdArn': response.get('SenderIdArn'),
                'MonthlyLeasingPrice': response.get('MonthlyLeasingPrice')
            })
            
        except Exception as e:
            results.append({
                'Country': country,
                'Status': 'Failed',
                'Error': str(e)
            })
            
        print(f"Completed {country}: {'Success' if results[-1]['Status'] == 'Success' else 'Failed'}")
    
    return results

def lambda_handler(event: Dict[str, Any], context: Any) -> Dict[str, Any]:
    try:
        # Extract parameters from event
        sender_id = event['sender_id']
        countries = [c.strip().upper() for c in event['countries'] if c.strip()]
        tags = event.get('tags')  # Optional
        message_types = event.get('message_types', ["TRANSACTIONAL", "PROMOTIONAL"])  # Optional
        
        # Validate input
        validate_input(sender_id, countries)
        
        # Initialize the AWS SMS Voice v2 client
        client = boto3.client('pinpoint-sms-voice-v2')
        
        # Process the request
        results = request_sender_id(
            client=client,
            sender_id=sender_id,
            countries=countries,
            message_types=message_types,
            tags=tags
        )
        
        # Calculate summary
        successful = sum(1 for r in results if r['Status'] == 'Success')
        
        return {
            'statusCode': 200,
            'body': {
                'results': results,
                'summary': {
                    'total': len(countries),
                    'successful': successful,
                    'failed': len(countries) - successful
                }
            }
        }
        
    except Exception as e:
        return {
            'statusCode': 500,
            'body': {
                'error': str(e)
            }
        }

How the Lambda Function Works to Configure Sender IDs

The Lambda function automates the Sender ID configuration process through these key steps:

• Input Validation: Ensures the Sender ID meets format requirements (1-11 alphanumeric characters, with optional underscores or hyphens).
• Bulk Registration: Processes each country sequentially with built-in rate limiting (1 request per second) to prevent API throttling.
• Logging: Returns the full ARN of each successfully configured Sender ID
• Flexible Configuration Settings:
  • Supports multiple message types (transactional, promotional, or both)
  • Enables resource tagging for organizational and cost tracking
  • Provides deletion protection to prevent accidental removal
• Cost Transparency: Displays monthly leasing price for each successful country configuration
• Error Handling: Individual country failures don’t halt the entire process, allowing partial success if a single country were to fail for some reason.

Using the Lambda Function

To use this function, create a Lambda with the code above and configure an event. The tags are optional and we have provided an example below:
NOTE: Depending on the number of countries you are attempting to register at a time, you may need to increase the 3 second default Lambda timeout. For reference, in our testing, we were able to do all Sender IDs(160) in less than 3 minutes.

Test Event Example

{
    "sender_id": "YourBrand",
    "countries": ["GB", "DE", "FR"],
    "tags": [
        {
            "Key": "Environment",
            "Value": "Production"
        },
        {
            "Key": "Department",
            "Value": "Marketing"
        }
    ]
}

IAM Permissions

Your Lambda will need these minimum AWS Identity and Access Management (IAM) permissions, scale back the resource if necessary:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "sms-voice:RequestSenderId",
                "sms-voice:TagResource"
            ],
            "Resource": "arn:aws:sms-voice:*:**ACCOUNT#**:sender-id/*"
        }
    ]
}

The Trust Policy required for Lambda to assume the role:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "lambda.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

Results Example

The Lambda will return results for each country, including configuration status and monthly costs, if any. Below you will see an example of 3 countries being configured:

{
  "statusCode": 200,
  "body": {
    "results": [
      {
        "Country": "GB",
        "Status": "Success",
        "SenderIdArn": "arn:aws:sms-voice:us-west-2:**ACCOUNT#**:sender-id/LAMBDATEST2/GB",
        "MonthlyLeasingPrice": "0.00"
      },
      {
        "Country": "DE",
        "Status": "Success",
        "SenderIdArn": "arn:aws:sms-voice:us-west-2:**ACCOUNT#**:sender-id/LAMBDATEST2/DE",
        "MonthlyLeasingPrice": "0.00"
      },
      {
        "Country": "FR",
        "Status": "Success",
        "SenderIdArn": "arn:aws:sms-voice:us-west-2:**ACCOUNT#**:sender-id/LAMBDATEST2/FR",
        "MonthlyLeasingPrice": "0.00"
      }
    ],
    "summary": {
      "total": 3,
      "successful": 3,
      "failed": 0
    }
  }
}
Function Logs:
START RequestId: 81d2d144-9023-413d-b976-c87c79a82eae Version: $LATEST
Processing country: GB (1/3)
Completed GB: Success
Processing country: DE (2/3)
Completed DE: Success
Processing country: FR (3/3)
Completed FR: Success

After processing your Sender ID configurations, it’s crucial to verify them. You can do this via the AWS console or by using the DescribeSenderIds API. This API offers flexible retrieval options:

• Specify individual Sender IDs for targeted information
  • Providing an invalid Sender ID will result in an error
• Apply filters to narrow your results
• Retrieve all Sender IDs associated with your AWS account by omitting both

Conclusion

Automating Sender ID configuration with the AWS End User Messaging v2 API and a Lambda function will dramatically reduce the time spent on manual configuration, ensure consistent branding across all supported and configured countries, and simplify a complex process. You’ll gain a scalable, reliable solution that allows you to deploy and manage your Sender IDs with confidence.

Additional resources:

AWS End User Messaging SMS documentation

SMS V2 API

Post Syndicated from Tyler Holmes original https://aws.amazon.com/blogs/messaging-and-targeting/how-to-register-a-sender-id-using-apis-with-aws-end-user-messaging/

Introduction

Welcome to our comprehensive guide on using the AWS End User Messaging V2 APIs to obtain a Sender ID in countries that require registration. Sender ID registration is a crucial step for businesses looking to establish a trusted communication channel with their customers via SMS. In countries such as Jordan, the Philippines, Qatar, and others registering a Sender ID is mandatory to ensure compliance with local regulations and to enhance message deliverability. You can view a list of countries that support Sender ID and require registration here.

NOTE: This post is specific to Sender IDs, to learn more about choosing the right originator for your use case read this post on How to Send SMS Globally Using AWS End User Messaging.

This guide will walk you through the high-level process of creating and submitting a Sender ID registration using AWS End User Messaging V2 APIs. While we will use Jordan as a case study in this post, the principles and steps outlined here apply to other countries with similar registration requirements for Sender ID.

High-Level Understanding of the Registration APIs

To successfully register a Sender ID, you’ll need to interact with several AWS End User Messaging APIs. Here’s a brief overview of the key APIs involved and their roles in the registration process:

1. DescribeRegistrationTypeDefinitions

• Purpose: Retrieves the specified registration type definitions.
• Use Case: View the requirements for creating, filling out, and submitting each registration type.
• Key Point: Each country has a specific “RegistrationType” that needs to be used in the next step to create a registration.
• Documentation: DescribeRegistrationTypeDefinitions

2. CreateRegistration

• Purpose: Creates a new registration “container”. This is an empty registration that we are going to fill with our data in later steps.
• Key Field: RegistrationType
  • Controls the type of registration (e.g., Toll-Free, 10DLC, JO_SENDER_ID_REGISTRATION, etc.).
• Documentation: CreateRegistration

3. DescribeRegistrationFieldDefinitions

• Purpose: Retrieves the specified RegistrationType field definitions.
• Use Case: View the requirements for creating, filling out, and submitting each registration type. There are different field types (SELECT, TEXT, ATTACHMENT) dependent on the type of data required to register as well as the actual questions that need to be answered.
• Documentation: DescribeRegistrationFieldDefinitions

4. CreateRegistrationAttachment

• Purpose: Uploads additional documentation that some countries require. Not all countries require documentation that needs to be uploaded so this may be an optional step depending on the country you are registering for. We will be registering for Jordan in this example which does require us to upload a document to complete the registration.
• Key Field: RegistrationAttachmentId
  • Used in the next action to include an attachment in the registration when you are required to provide one. Not all registration types require an attachment.
• File Specifications:
  • Maximum file size: 500kb
  • Valid file extensions: PDF, JPEG, or PNG
• Documentation: CreateRegistrationAttachment

5. PutRegistrationFieldValue

• Purpose: Sets the value for a specific registration field.
  • This action needs to be repeated for all required fields.
• Documentation: PutRegistrationFieldValue

6. SubmitRegistrationVersion

• Purpose: Submits the specified registration version for review and approval. You are able to create new versions of the registration using CreateRegistrationVersion so make sure if you created another Registration Version that you use the correct ID.
• Important Notes:
  • Ensure that you are using the correct Version if you created multiple
  • Ensure all data is correct before submission.
  • Initial status will be “CREATED” and should change to “REVIEWING” within 24 hours.
  • You cannot edit or delete the registration until it is approved or rejected.
• Documentation: SubmitRegistrationVersion

Detailed Steps for Sender ID Registration in Jordan

In the following sections, we’ll dive deeper into each of these steps, providing more detail on the API calls and responses as well as best practices to ensure a smooth registration process. Whether you’re registering in Jordan or another country with similar requirements, this guide will equip you with the knowledge you need to successfully register a Sender ID.

Step 1: DescribeRegistrationTypeDefinitions

The first step is to run DescribeRegistrationTypeDefinitions to retrieve all specified registration type definitions. This API provides a detailed response that includes various attributes related to the registration process. Let’s break down these attributes for Jordan:

• Country: JO
  • Description: Specifies the country code for which the registration type definitions are being described. JO stands for Jordan.
  • Implication: Understanding the country code is crucial because registration requirements and processes can vary significantly from one country to another.
• ResourceType: SENDER_ID
  • Description: Indicates the type of resource for which the registration is being defined.
  • Implication: Knowing that the resource type is SENDER_ID helps you understand that the registration process is focused on obtaining approval specifically for a Sender ID as there are some countries that have multiple registration types.
• Registration Type: JO_SENDER_ID_REGISTRATION
  • Description: Specifies the exact type of registration required for the given country and resource type.
  • Implication: This registration type is critical because it dictates the specific steps, documentation, and criteria you need to meet to successfully register a Sender ID in Jordan.
  • You will use this value to create the initial registration
• Association Behavior: ASSOCIATE_ON_APPROVAL
  • Description: Describes how the registered Sender ID will be associated with your AWS account once the registration is approved.
  • Implication: ASSOCIATE_ON_APPROVAL means that the Sender ID will be automatically associated with your account as soon as the registration is approved, simplifying the process post-approval. There will be nothing more for you to do once you have successfully submitted your registration and it has been approved. Some registration types require steps to be taken after the registration is approved, this is not one of them.
• Disassociation Behavior: DISASSOCIATE_ALL_CLOSES_REGISTRATION
  • Description: Explains what happens when you disassociate the Sender ID from your account.
  • Implication: This behavior is important to note because it means that the origination identity must be disassociated from the registration before the registration can be closed.

Step 2: CreateRegistration

Next, use CreateRegistration with the RegistrationType for Jordan, “JO_SENDER_ID_REGISTRATION,” to generate a blank registration “container” for a Jordan Sender ID. Make sure to log the “RegistrationId” for later use as it will be used throughout the rest of the process.

Below is a screenshot of the registration that was created in the console

Step 3: DescribeRegistrationFieldDefinitions

Use DescribeRegistrationFieldDefinitions with “JO_SENDER_ID_REGISTRATION” as the RegistrationType to pull down all the fields that need to be filled out to submit the registration.

Important Field Attributes

• FieldPath
  • Value: A string that specifies the path to the field within the registration form (e.g., companyInfo.companyName).
  • Description: The FieldPath attribute provides a hierarchical path to the specific field within the registration form. It identifies one of the fields we will use later to input the data into our registration
  • Implication: Ensures that you place the required information in the correct field, essential for accurate processing.
• FieldRequirement
  • Value: Indicates whether the field is required, optional, or conditional (REQUIRED, OPTIONAL, CONDITIONAL).
  • Description: The FieldRequirement attribute specifies the necessity of the field in the registration process. A REQUIRED field must be filled out for the registration to be submitted, while an OPTIONAL field can be left blank if not applicable. A CONDITIONAL field depends on other fields and may become required based on certain conditions.
  • Implication: Helps prioritize which fields to complete and ensures critical information is not missed.
• FieldType
  • Value: Describes the type of data expected in the field (SELECT, TEXT, ATTACHMENT).
  • Description: Indicates the format and type of data that should be entered into the field.
  • Implication: Ensures the registration form is valid and reduces the risk of errors or rejections due to incorrect data formats.

See the categories of the Jordan registration in the screenshot below

Let’s break down the required fields that are common across all Sender Id registrations and their descriptions in a more readable format:

Sender ID Information:

1. Sender ID (Required)
   1. Must be 3-11 alphanumeric characters
   2. Must contain at least one letter
   3. Example: “EXAMPLE”
2. Sender ID Description (Optional)
   1. Explain the connection between company name and sender ID
   2. Max 500 characters
3. Proof of Sender ID Connection (Optional)
   1. Required only if the connection between company name and sender ID isn’t obvious
   2. Must provide evidence of intellectual property rights

Below is a screenshot of the Console version

Company Information:

1. Company Name (Required)
   1. Legal company name
   2. Max 100 characters
   3. Example: “Example Corp”
2. Company ID (Required)
   1. Legal identification number (EIN/VAT)
   2. Alphanumeric only
   3. Max 30 characters
3. DBA Name (Optional)
   1. “Doing Business As” name if different from legal name
   2. Max 100 characters
4. Website (Required)
   1. Company’s full URL
   2. Example: “https://www.example.com”
5. Area of Business (Required)
   1. Choose one: Agriculture, Communication, Construction, Education, Energy, Entertainment, Financial, Government, Healthcare, Hospitality, Insurance, Manufacturing, Real estate, Retail, Technology, Other

Below is a screenshot of the Console version

Company Address:

1. Address Line 1 (Required)
2. Address Line 2 (Optional)
3. City (Required)
4. State/Province (Optional)
5. Postal Code (Optional)
6. Country Code (Required)
   1. Two-letter ISO code
   2. Example: “US”

Below is a screenshot of the Console version

Contact Information:

1. Email Address (Required)
   1. Valid email format
   2. Example: “[email protected] “
2. Phone Number (Required)
   1. Must contain at least 3 digits
   2. Example: “+12065550100“

Below is a screenshot of the Console version

Messaging Use Case:

1. Use Case Category (Required)
   1. Choose one: One-time passcodes, Account/security alerts, Purchase/delivery notifications, Public service announcements, Polling/surveys, Info on demand, Other
2. Use Case Description (Required)
   1. Max 500 characters
3. Monthly Message Volume (Required)
   1. Choose one: 10, 100, 1,000, 10,000, 100,000, 1,000,000, 10,000,000+
4. Opt-in Description (Required)
   1. How users will opt-in to receiving messages
   2. Max 500 characters

Below is a screenshot of the Console version

Message Samples:

1. Message Sample 1 (Required)
   1. Max 306 characters
2. Message Sample 2 (Optional)
   1. Max 306 characters
3. Message Sample 3 (Optional)
   1. Max 306 characters

Below is a screenshot of the Console version

Jordan-Specific Requirements

Some countries, not all, also have country-specific requirements. Jordan requires the following for this registration:

1. Company Registration Documentation (Required)
   1. Must provide company registration docs (both local and international companies)
   2. This is an Attachment type so we will need to use “CreateRegistrationAttachment” first in order to put this value into the registration. We will cover this further down in the process
2. Transactional Acknowledgement (Required)
   1. Must acknowledge that only transactional messages will be sent
   2. Promotional content is not allowed
   3. This is a “Select” field type with the only option being “Yes” meaning you will be unable to register unless you agree to this acknowledgement

Below is a screenshot of the Console version

Step 4: CreateRegistrationAttachment

Now that you know all the fields required for the Jordan Sender ID registration, you need to gather all the necessary data, including the required attachment. The Jordan Sender ID registration requires only one attachment. Let’s review how to add this attachment to your registration.

To add an attachment to your registration, use the CreateRegistrationAttachment API. You have two options for providing this document:

1. Specify a file in S3:
   1. Ensure you use Standard buckets, S3 Express is not supported.
2. Upload it as a Base64-encoded binary data object:
   1. This method allows you to directly upload the document without needing to store it in S3 first.

Important: After successfully running the CreateRegistrationAttachment command, you will receive a “RegistrationAttachmentId.” Make sure to log this ID, as you will need it to attach the upload to your registration.

Step 5: PutRegistrationFieldValue

Use PutRegistrationFieldValue to input data into each field. Loop through each input as each call only inputs a single value. Specify the “RegistrationId” logged earlier when making each call. Your options for field values are:

• RegistrationAttachmentId: The unique identifier for the registration attachment
• SelectChoices: An array of values for the form field that were specified in the payload earlier
• TextValue: The text data for a free form field

Step 6: Review your registration

Once you have successfully inputted all the values for your registration, you can review your inputs in one of two ways:

1. View in the Console:
   1. Your registration details are accessible directly in the AWS Management Console.
2. Use DescribeRegistrationFieldValues:
   1. You can pull down your registration and review each of its values using the DescribeRegistrationFieldValues API. Make sure to use the right version ID of your registration.

Step 7: Submitting Your Registration

Once all values in your registration are complete and correct, submit your registration for review using the SubmitRegistrationVersion API. Provide your “RegistrationId” when making this call.

Initial Status:

• The initial status of your registration will be “CREATED.”
• It should change to “REVIEWING” within 24 hours.
• If the status does not change from “CREATED” to “REVIEWING” within 24 hours and you’ve confirmed you SUBMITTED your registration version, create a support case for assistance.

Sender ID Registration Review Process

Each country has its own review process and timeline. Each registration is examined on a first-in/first-out basis by the registrar for each country. AWS does not review your registrations so make sure that you are completing this registration with this in mind. There are humans reviewing these registrations that do not know your company or your use case so make sure to be clear and concise in your responses.

If the registrar is confused by your submission, they may reject it, and you will need to start the process over, amending the registration where necessary and resubmitting. This puts you in the back of the line again, which will increase your timeline.

Conclusion

Completing a Sender ID registration using the End User Messaging V2 APIs involves several steps, each critical to ensuring compliance and successful registration. By following this guide, you can navigate the process efficiently, from understanding the required fields to submitting your registration for review. Whether you’re registering in Jordan or another country with different requirements, this guide provides the knowledge and steps needed to successfully obtain a Sender ID and establish a trusted communication channel with your customers via SMS.

Post Syndicated from Bruno Giorgini original https://aws.amazon.com/blogs/messaging-and-targeting/whatsapp-aws-end-user-messaging-social/

In today’s world, WhatsApp has become a widely used communication app, with over 2.7 billion users globally. As a business owner, you likely have customers who use WhatsApp regularly. This presents an opportunity to use WhatsApp as an additional channel to increase your reach and engage with your customers more effectively. WhatsApp messaging need not be limited to one-on-one interactions with your customers. You can also use it to automate some of your business workflows. These workflows can be part of your existing workloads running on AWS, or you can build new automations using AWS services.

AWS End User Messaging Social natively links your WhatsApp Business Account (WABA) and your AWS account. This helps simplify building integrations between your customer’s WhatsApp messenger app and your workloads running on AWS. Additionally, it also provides unified billing experience within AWS.

This post walks through a solution to establish this integration and automate your business workflows using WhatsApp and End User Messaging Social.

Overview of solution

The solution uses End User Messaging Social to integrate your workload deployed on AWS with your Meta business portfolio. This allows you to receive WhatsApp messages that your end customers send, directly in your AWS environment. An incoming WhatsApp message that End User Messaging Social receives triggers an Amazon Simple Notification Service (SNS) notification, which then activates an AWS Lambda function. This Lambda function processes the request and then sends a WhatsApp message as a response to the user. You can build complex business workflows and automated WhatsApp marketing expanding this solution.

Figure 1: Solution Architecture

IMPORTANT: Note that any WhatsApp user can send a message to your WABA number and trigger the workflow. To avoid incurring ongoing charges, complete the steps in the “Cleaning up” section.

Prerequisites

Before starting this walkthrough, ensure you have:

1. An AWS account
2. A Meta business portfolio. Create one by following these instructions
3. A phone number to create a WABA
4. A phone with WhatsApp Messenger app installed to test the solution. Note that the mobile app uses a different phone number than the one that is associated with your WABA.
5. AWS CLI installed and configured to access to your AWS account
6. Serverless Application Model CLI to deploy the sample application
7. node.js >= 22.x

Implementing the solution

Step 1: Create an SNS topic

1. Navigate to the SNS page.
2. Use the AWS region where you plan to use End User Messaging Social.
3. Select “Standard” as the topic “Type”
4. Enter “WhatsAppIncomingMessages” as the “Name” of the topic
5. Click on the “Create topic” button.
6. In the topics details that appear, note the “ARN” of the topic

Step 2: Add WABA to AWS End User Messaging

1. Navigate to the WABA page.
2. Click on the “Add WhatsApp phone number” button
3. Click on “Launch Facebook portal” to connect your AWS account and your Meta business portfolio.
4. Follow the instructions in the Facebook pop-up to complete the registration. Below are screenshots of the key steps in the process:

Figure 2: Connect AWS and Meta Business Portfolio

1. After the Facebook signup popup closes, you will see this “Link established” message on your AWS console. Enter the ARN of the SNS topic created in Step 1 in the “Message and event destination” section.

Figure 3: Successfully linked WABA and AWS account

[Alt text: Screenshot of the AWS console that shows an established connection between AWS and WABA account and the SNS topic]

1. Click “Add phone number” to complete linking your WhatsApp business account with your AWS account.

7. Navigate to the WABA page and verify that the added account is in “Active” status.
8. Click on the Business account ID you added to navigate to the details page.
9. From the “Phone Numbers” section, note the “Phone number ID” of the number that you added.

Step 3: Deploy the Lambda function to handle customer WhatsApp messages

1. Clone the example repository and deploy the Lambda function by following the steps below:

$ git clone https://github.com/aws-samples/aws-end-user-messaging-social-automation.git

$ cd aws-end-user-messaging-social-automation/

2. Build the project by running this command:

$ sam build

3. Deploy the application by running the command below and follow the prompts:

$ sam deploy --guided
...
# Enter the details for questions asked
Stack Name [sam-app]: EndUserMessagingWhatsApp
AWS Region [us-east-1]: <AWS region where you have created the WABA account>
Parameter SNSTopicArn []: <ARN of the SNS topic created in Step 1>
Parameter PhoneNumberID []: <Phone number ID from Step 2>

Accept the defaults of the rest of the questions to complete the deployment. This will create a Lambda function that is triggered when a WhatsApp message is sent to your WABA number

Step 4: Testing the solution

1. From a phone that has WhatsApp installed, send this message to your WABA phone number

Hello

2. Validate that you see the following in response to the previous message:
   1. Blue check mark, indicating the message has been received and read
   2. A reaction to your message
   3. A reply message saying “Hello {profile name}, how can we help you?”
   4. A list of options to choose from
3. Select one of the options
4. You will receive a static message pointing you to find more information about the End User Social in the documentation page. The interaction will look like the picture below:

Figure 4: End user’s WhatsApp interaction with the business

Troubleshooting

Access the logs of your lambda function by navigating to the CloudWatch logs page and searching for “WhatsAppMessageHandler” in the search box. Select the log group of your Lambda function and click on the log stream corresponding to the time you ran the test. The Lambda function logs information when a message is received and processed. However, Lambda’s received SNS events and extracted user messages are deliberately excluded from CloudWatch logs. The event contains information such as sender’s phone number and WhatsApp profile name that can be classified as sensitive by your business. Check your organization’s data handling policies before logging this information. Find more information on the message structure of the different message types in Meta developer documentation.

You can also use AWS CLI to send messages to customers. You can send messages of “text” type if your customer has already initiated a conversation with you. Run the command below to send a reply to a WhatsApp message:

aws socialmessaging send-whatsapp-message \
--cli-binary-format raw-in-base64-out \
--message '{"messaging_product": "whatsapp", "to": "+15554567890", "text": { "preview_url": false, "body": "Hello! How can we help you?"}}' \
--origination-phone-number-id phone-number-id-beac123456789abcdefgh \
--meta-api-version v20.0

Note that you can only send messages of type “text” to customer if they have started a conversation with you and it has been less than 24 hours since the last time they messaged you. Use templated messages to start conversations with your customers, for example, to send an OTP (one-time password) or marketing messages. Meta needs to approve message templates before you can send them to customers.

Monitoring

End User Messaging Social can publish data related to cost of using the service to CloudWatch metrics. To enable this, enter the command below to create a IAM service linked role called “AWSServiceRoleForSocialMessaging”:

aws iam create-service-linked-role --aws-service-name social-messaging.amazonaws.com

You can monitor AWS End User Messaging Social using CloudWatch to view metrics:

• WhatsAppMessageFeeCount
• WhatsAppConversationFeeCount

You can get also get notified when a specific threshold is reached by setting up a CloudWatch alarm on these metrics. This can help you keep track of costs associated with End User Messaging Social.

Cleaning up

Note that any WhatsApp user can send a message to your WABA number and trigger the workflow. To avoid incurring ongoing charges, complete the following cleanup steps:

1. To delete the Lambda function and the associated resources, run the following command:

sam delete

1. To delete the End User Messaging Social resources, navigate to the WABA page. Select the Business account ID of your WABA and click on the “Unlink” button.

Conclusion

This post shows how you can simplify the integration between WhatsApp and your workloads running on AWS, allowing you to automate interactions with your end customers. It shows how you can trigger a Lambda function from a WhatsApp message initiated by your end customer. You can extend this solution to build more complex workflows, for example triggering an AWS Step Functions , invoking your container based workloads running on AWS among others.

For more information, see the following resources:

• WABA message templates
• Working with media files
• Best practices for End User Messaging Social