Deploying with Amazon Web Services

This document shows you how to use Amazon Web Services (AWS) to deploy the WhatsApp Business API. The process can be divided into two main steps:

1. WhatsApp Business API client Deployment
2. WhatsApp Business API client Configuration

Once you have completed the set up, you can choose to upgrade the client. If you ever need to restart both the Webapp and CoreApp, follow these steps.

Get Started

Before you start you will need to:

• Set up an AWS Account ID
• Create an AWS Key Pair
• Subscribe to a CentOS 7 Image
• Deploy in a supported region

Set up an AWS Account ID

You need to set up a valid AWS account and be familiar with working on AWS. WhatsApp provides CloudFormation templates for deploying the WhatsApp Business API client easily. Refer to the AWS Getting Started Resource Center for more information.

Create an AWS Key Pair

You need to create a new key pair to access the EC2 instance created by the WhatsApp Business API template. You can also use a previously created key pair. Refer to the Amazon EC2 Key Pairs documentation for information about creating and using key pairs with an EC2 instance.

Subscribe to a CentOS 7 Image

The WhatsApp Business API client makes use of a CentOS 7 image (available in the AWS Marketplace). Terms and conditions should be reviewed and accepted before using the template. Failure to accept the terms will lead to the template creation failure.

To review and accept the CentOS 7 AMI image:

1. Go to the AWS Marketplace: CentOS 7 (x86_64) - with Updates HVM page.
2. Click Continue to Subscribe in the upper right corner, then click the Accept Terms button.

Accepting the CentOS terms

Supported Regions

The WhatsApp Business API templates use the EFS resource type, which is not available in all AWS regions. Hence, only the following regions are currently supported:

• N. Virginia (us-east-1)
• Ohio (us-east-2)
• N. California (us-west-1)
• Oregon (us-west-2)
• Mumbai (ap-south-1)
• Seoul (ap-northeast-2)
• Singapore (ap-southeast-1)
• Sydney (ap-southeast-2)
• Tokyo (ap-northeast-1)
• Frankfurt (eu-central-1)
• Ireland (eu-west-1)

FAQ

Deployment

Step 1: [Optional] Network Setup

The Virtual Private Cloud (VPC) network is generally created when you sign up for an AWS account. Further, there could be several customizations and access control restrictions required that are specific to an enterprise business.

If the VPC network infrastructure is already created, you can skip this step. Otherwise, the following template can be used to create the network infrastructure on AWS.

Network Requirements

• There must be at least two subnets in different availability zones within the region. Otherwise, template creation will fail while creating the RDS (database) resource.
• It should allow inbound access to HTTP (port: 80), HTTPS (port: 443) and SSH (port: 22). For security reasons, it is highly recommended you use HTTPS and avoid HTTP.

To deploy the network template:

1. Go to the CloudFormation console for your region (for example, eu-west-1).
2. Select Create a stack.
3. Choose Amazon S3 URL as the Template Source.
   

   Create Stack
4. Enter https://wa-biz-cfn.s3.amazonaws.com/wa_ent_net.yml and click Next, or click
   
   Deploy Template
   
   and choose the appropriate region, if needed, from upper right corner of the webpage.
5. On the Specify stack details screen, input the parameter values according to the table below:

Parameters

Availability Zones Configuration

VPC Configuration

Public Subnet Configuration

Private Subnet Configuration

Step 2: Upload DB and Monitoring Stack Configuration Files

Before deploying the WhatsApp Business API stack on AWS, you need to first upload referenced substacks’ configuration files to an S3 bucket that you have read access to.

1. Create a new S3 bucket or use an existing S3 bucket that you have read access to.
2. Download the wa_ent_db.yml file and the wa_ent_monitoring.yml file from GitHub and upload both of them to the S3 bucket mentioned in step 1.
3. Choose the wa_ent_db.yml file from the Objects list, and copy its URL. It should be in the format of https://xxx.s3.<avalability_zone>.amazonaws.com/wa_ent_db.yml.
4. In the wa_ent.yml file, replace the value of the TemplateURL in the dbStack with the object URL from step 3 and save the file.
5. Choose the wa_ent_monitoring.yml file from the Objects list, and copy its URL. It should be in the format of https://xxx.s3.<avalability_zone>.amazonaws.com/wa_ent_monitoring.yml.
6. In the wa_ent.yml file, replace the value of the TemplateURL in the Monitoring stack with the object URL from step 5 and save the file.

Upload to S3 Bucket

Step 3: WhatsApp Business API Deployment

WhatsApp Enterprise is the main template and creates all the resources (except the network) required for the WhatsApp Business API client. As noted earlier, this template also creates a database resource, if required.

To deploy the WhatsApp Business API client:

1. Go to the CloudFormation console for your region (for example, eu-west-1).
2. Select Create a stack.
3. Download the wa_ent.yml file from GitHub and save it locally.
4. Choose Upload a template file as the template source and upload the template file downloaded from step 3.
   

   Create Stack
5. Click Next
   
6. You will then be able to enter parameters. Refer to the table below for parameter descriptions.
   
7. After setting all parameters (in the tables below), click Next onto the Configure stack options page. You may make any necessary changes based on your preferences and click Next.
8. On the Review stack page, you will see a summary of parameter values and stack options. After verification, in the Capabilities section, check both boxes and click Submit to start creating the stack.
   Note: The deployment takes about 20-30 minutes.
   

Parameters

General Configuration

Network Configuration

Container Configuration

Database Configuration

Logging Configuration

Filesystem Configuration

Security Configuration

WhatsApp Business API Access Point

These parameters are required for Grafana dashboards to retrieve application metrics for monitoring purposes.

Grafana

Output after Deployment

Upon successful creation of template, the following parameters are displayed:

• Load balancer name: Hostname of the load balancer accessing the WhatsApp Business Platform API client
• Database hostname: Hostname of the database that is created or provided during template creation
• Database port number: Port number for the database connection
• ECS cluster name: Name of the ECS cluster created
• Log retention days: Number of days to retain logs
• DB connection CA: Value of DB Connection CA if configured
• DB connection cert: Value of DB Connection cert if configured
• DB connection key: Value of DB Connection key if configured
• Grafana: Grafana Dashboard URL
• ShardCount: Number of shards to configure for the WhatsApp Business Platform API

Edit SSH Security Rules

By default, the security rules created by the stack allow all traffic to be able to reach the EC2 instances through SSH, the API endpoints and Grafana dashboard through HTTPs, and the cadvisor and Prometheus containers. For security reasons, you are highly recommended to close off unnecessary access. This section will illustrate the steps updating the SSH security rule as an example. You should always restrict SSH access to only traffic you trust.

1. In the EC2 - Security Groups console (for instance: EC2 Management Console (amazon.com)):
   1. Select the correct region in the upper right corner.
   2. Select the security group that contains <stackName>-EcsSecurityGroup, then switch to the Inbound Rules tab.
      

      Edit Inbound Rules
   3. Select Edit inbound rules, update the Source column to only allow trusted traffic (for instance: My IP) to access EC2 hosts through SSH.
      
   4. After adjusting all security rules, click Save rules to apply the changes.
   5. Repeat these changes for the security group that contains "<stackName>-ms-xxx-EcsSecurityGroup" to restrict SSH access for the monitoring stack.

WhatsApp Business API Client Configuration

Once the WhatsApp Business API client is successfully deployed, it needs to be configured to bring it into operation.

Step 1: Phone Registration

Refer to the Phone Number guide for more in-depth information about phone number registration.

Download the base64-encoded certificate from your WhatsApp account in the Facebook Business Manager under the Phone Numbers tab of the WhatsApp Manager.

Once you have the correct phone number selected and have the base64-encoded certificate, you need to register the WhatsApp Business API client via the account node. Refer to the Registration documentation for more information.

Step 2: Set Shards

After the stack is created, you need to use the shards API call to increase the number of active Coreapp instances to achieve the desired throughput. The number of shards can be found in the Output section of the stack.

Step 3: Update Application Settings

The configuration of WhatsApp Business API web callbacks and other parameters is described in the Application Settings documentation. To achieve stable throughput, the following application settings are recommended.

 {
    "settings": {
        "application": {
            "callback_backoff_delay_ms": 3000,
            "callback_persist": true,
            "db_garbagecollector_enable": false, # change this to true when there are no ongoing messaging campaigns
            "heartbeat_interval": 5,
            "max_callback_backoff_delay_ms": 900000,
            "media": {
                "auto_download": [
                    "document",
                    "image",
                    "video",
                    "voice",
                    "sticker",
                    "audio"
                ]
            },
            "notify_user_change_number": true,
            "pass_through": false,
            "sent_status": true,
            "show_security_notifications": false,
            "skip_referral_media_download": false,
            "unhealthy_interval": 30,
            "wa_id": "12245552741",
            "webhooks": {
                "max_concurrent_requests": 24,
                "message": {
                    "delivered": true,
                    "read": true,
                    "sent": true
                },
                "url": "<YOUR_WEBHOOK_SERVER_URL>"
            }
        }
    },
    "meta": {
        "api_status": "stable",
        "version": "2.41.3"
    }
}

      
      
    

Step 4: [Optional] SSL Configuration

The WhatsApp Business API client generates a self-signed certificate by default when it is created. The Certification Authority (CA) certificate used to generate the self-signed certificate might be required to verify the WhatsApp Business API client endpoint and to avoid a certificate trust warning.

You can download the CA certificate and store it locally to avoid the certificate trust warning, or upload your own. Refer to the certificate node documentation for more information.

Step 5: Validation of the Setup

Once the configuration and registration steps are successful, a message can be sent and received to validate the basic functionality of WhatsApp Business API client. This is fully described in the Messages documentation.

Upon successful receipt of a message, the WhatsApp Business API client will POST the message status/details to the Webhook configured in Step 3.

If your message was successfully received, congratulations, you are all set! Please refer to the Reference documentation for more information on the available API endpoints.

Restarting the Coreapp and Webapp

To restart the WhatsApp Business API client, in the the ECS console (for example, https://us-west-2.console.aws.amazon.com/ecs/home?region=us-west-2#/clusters):

1. Select the correct region in the upper right corner.
2. Select the appropriate cluster from the list.
3. Under the Services tab, select the service name that contains WAEntService.
4. Select the Tasks tab. There should typically be only one task, with an ID made of hex digits.
5. In the Tasks window, click Stop in the upper right corner, then click Stop again when prompted.

This stops both the Webapp and CoreApp. Shortly after, the AWS infrastructure restarts both the Webapp and CoreApp.

Upgrading

This section walks through how to upgrade both the WhatsApp Business API Client and the CloudFormation (CFN) Template. Performing an upgrade will result in a downtime, so do not send messages during this time. Resume sending messages only after the upgrade is complete.

You can upgrade the CFN Template and the WhatsApp Business API client version at the same time by doing the following:

1. In Step 5 of the WhatsApp Business API Client Upgrade instructions, instead of Use current template, select Replace current template.
2. In the Specify template section, choose “Upload a template file” and choose the latest template file downloaded from GitHub.

WhatsApp Business API Client Upgrade

1. Go to the CFN console (for example, https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks?filter=active).
2. Select the correct region in the upper right corner.
3. Select the WhatsApp Business API client stack that was already created.
4. Click Update.
5. On the Prerequisite - Prepare template page, select the Replace current template option. In the Specify template section, choose “Upload a template file” and choose the latest template file downloaded from GitHub. Click Next.
6. On the Specify stack details page, change the WhatsApp Business API Client (container) version to the desired version. DO NOT CHANGE any other parameter. Click Next.
7. On the Configure stack options page, click Next.
8. On the Review page, select "I acknowledge that AWS CloudFormation might create IAM resources with custom names." Review the Change set preview section for any unexpected changes. If there are any unexpected changes or you are unsure, please contact WhatsApp Direct Support. Click Update stack. The Stack Update status can be tracked in the CFN console and will change from UPDATE_IN_PROGRESS to UPDATE_COMPLETE once the upgrade is finished.

WhatsApp CFN Template Upgrade

1. Go to the CFN console (for example, https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks?filter=active).
2. Select the correct region in the upper right corner.
3. Select the WhatsApp Business API client stack that was already created.
4. Click Update.
5. On the Prerequisite - Prepare template page, select the Replace current template option. In the Specify template section, choose “Upload a template file” and choose the latest template file downloaded from GitHub. Click Next.
6. On the Specify Stack Details page, enter the appropriate parameters, per the information in previous sections. Click Next.
7. On the Configure Stack Options page, click Next.
8. On the Review page, select "I acknowledge that AWS CloudFormation might create IAM resources with custom names." Review the Change set preview section for any unexpected changes. If there are any unexpected changes or you are unsure, please contact WhatsApp Direct Support. Click Update stack. The Stack Update status can be tracked in the CFN console and will change from UPDATE_IN_PROGRESS to UPDATE_COMPLETE once the upgrade is finished.

How to Manually Reduce Cost when your System in Idle (Optional)

It is common that businesses want to set up a high throughput environment for a time-bounded campaign and wish to keep a low-cost environment running during non-campaign time. This section offers suggestions on how to manually scale down the AWS setup to save cost.

1. In the ECS console (e.g.: Amazon ECS:)
   1. Select the correct region in the upper right corner.
   2. Select the appropriate cluster from the list.
   3. In the Services tab, select the service name that contains WAEntCoreappService. Choose Edit Service, and update the "Desired tasks" value to 0.
      

      Deployment Configuration
   4. Repeat step c for all other services, including WAEntWebService, WAEntMasterService, and HostExporterService.
   5. Go back to the cluster page, in the Tasks tab, make sure there are no running tasks of the above services.
2. In the EC2 - Auto Scaling Groups console (e.g.: Auto Scaling groups | EC2 Management Console (amazon.com)):
   1. Select the correct region in the upper right corner.
   2. Select the auto scaling group of the stack with HAECSAutoScalingGroup in the name, and choose Edit. Update both the “Desired capacity” and the “Minimum capacity” to 3.
      

      Group Size
   3. Select the auto scaling group of the stack with HAECSAutoScalingGroupWeb in the name, and choose Edit. Update both the “Desired capacity” and the “Minimum capacity” to 2.
3. (Optional) If the initial value of "Type of message" is any of the image types, you can replace the EC2 instance types with the cheaper option of c5.large.
   1. In the EC2 - Launch Templates console, select the appropriate launch template from the list.
   2. Select Actions - Modify template (create new version).
      

      Launch Templates Console
   3. In the Instance type section, update the Instance type to c5.large, then choose Create template version.
      

      Instance Type
   4. In the EC2 - Auto Scaling Groups console, select the auto scaling group of the stack with HAECSAutoScalingGroup in the name.
   5. Select Edit in the Launch template section.
   6. Select the new launch template created in step 3c and choose Update.
      

      Launch Template
4. In the RDS console (e.g.: RDS Management Console (amazon.com)):
   1. Select the correct region in the upper right corner.
   2. Select the appropriate Aurora database from the list.
   3. Select Modify, and update the DB instance class to r5.xlarge.
      

      Instance Configuration
5. In the ECS console (e.g.: Amazon ECS):
   1. Select the correct region in the upper right corner.
   2. Select the appropriate cluster from the list.
   3. In the Services tab, select the service name that contains WAEntCoreappService. Choose Edit Service, and update the "Desired tasks" value to 3.
   4. In the Services tab, select the service name that contains HostExporterService. Choose Edit Service, and update the "Desired tasks" value to 3.
   5. In the Services tab, select the service name that contains WAEntWebService. Choose Edit Service, and update the "Desired tasks" value to 2.
   6. In the Services tab, select the service name that contains WAEntMasterService. Choose Edit Service, and update the "Desired tasks" value to 2.
6. Wait for all services to launch the desired number of tasks. Once all tasks are running, use Set Shards API to reset the shards to 2.
7. Validate the health of the system with the Health API. A message can also be sent and received to validate the basic functionality of WhatsApp Business API client. This is fully described in the Messages documentation.