On-Premises API

We are sunsetting On-Premises API. Refer to our On-Premises API Sunset document for details, and to learn how to migrate to our next-generation Cloud API.

Deploying with Amazon Web Services - Archived Version

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.

This document walks through the old AWS template. Please refer to the new AWS template that we have tested for higher and more stable messaging throughput.

Before You Start

You will need:

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.

The key pair needs to be created using the region for which you are deploying the WhatsApp Business API.

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:

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

Depending on initial testing, WhatsApp will determine whether we can provide an alternate option that is available in all regions.

FAQ

No, we don't support KOPS. We do support the AWS solution based on ECS. We also have a general Kubernetes minikube setup.

Permalink

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.

The network template is provided for reference purposes only. You can modify it to your specific needs.

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

NameDescription

Stack name

Required.

Name of the stack to be created

Availability Zones Configuration

NameDescription

Availability zones

Required.

The availability zones (AZs) for creating the VPC
The template requires at least 2 AZs to be selected. For a production environment, it is recommended to select at least 3 AZs.

Number of availability zones

Required.

The number of availability zones selected

VPC Configuration

NameDescription

IP address range

Required.

The IP address range (CIDR) for this VPC

Tenancy

Required.

The VPC tenancy
Options: default, dedicated

Public Subnet Configuration

NameDescription

IP range - subnet #1

Required.

The IP address range (CIDR) for public subnets

IP range - subnet #2

Required.

The IP address range (CIDR) for public subnets

IP range - subnet #3

Optional.

Required if the number of availability zones is greater than 2.

IP range - subnet #4

Optional.

Required if the number of availability zones is greater than 3.

Private Subnet Configuration

NameDescription

Create private subnets?

Required.

Options: true (default), false
If a private subnet is not required for some reason, this flag can be set to false.

IP range - subnet #1

Conditional.

Required if the private subnet creation is set to true.

IP range - subnet #2

Conditional.

Required if the private subnet creation is set to true.

IP range - subnet #3

Conditional.

Required if the private subnet creation is set to true and the number of AZs is greater than 2.

IP range - subnet #4

Conditional.

Required if the private subnet creation is set to true and the number of AZs is greater than 3.

Step 2: [Optional] Database (RDS - MySQL) Setup

MySQL release 5.7xx is required.

The database password should not contain any of these characters: ?{}&~!()^/"@

Failing to comply with this will likely cause the setup to fail.

The WhatsApp Business API client uses the database (RDS - MySQL) to store information required for the functioning of the client.

Currently, the WhatsApp Business API client works only with a MySQL database backend.

It's highly recommended you create the database automatically with the WhatsApp Business API template below. However, if you already have a database set up, database creation can be skipped by providing the existing database's hostname.

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. Choose Amazon S3 URL as the Template Source.
    Create Stack
  4. Enter https://wa-biz-cfn.s3.amazonaws.com/wa_ent.yml and click Next, or click



    and choose an appropriate region, if needed, from the upper right corner of the webpage.
    Note: The deployment takes about 20-30 minutes.
  5. You will then be able to enter parameters. Refer to the table below for parameter descriptions.
    Enter Parameters

Parameters

NameDescription

Stack name

Required.

Name of the stack to be created.
For an internet-facing load balancer scheme, the stack name must be less than or equal to 22 characters. For an internal load balancer scheme, the stack name must be less than or equal to 12 characters.
Note: For deployments in the ap-southeast-1, ap-southeast-2, ap-northeast-1, or ap-northeast-2 regions, the stack name must use 8 characters or less.

If the stack name is longer then these requirements, the creation of the stack will hang and fail, as it will not be able to create the SSL certificate.

General Configuration

NameDescription

Environment type

Required.

Used to determine the minimum number of EC2 instances allocated in ECS autoscaling

High Availability

Optional.

Enables the static High Availability feature Default: disabled
Available as Beta.

Desired number of active 'coreapp' instances

Optional.

The number of desired active Coreapp instances, used to allocate resources (e.g.: EC2 instances) when creating the stack
Default: 2
This is only applicable for High Availability/Multiconnect mode.
After the stack is created, you need to use the shards API call to increase the number of active Coreapp instances.

Network Configuration

NameDescription

VPC

Required.

The VPC for this deployment.
WhatsApp also provides a sample/reference template to create a VPC with public and private subnets. The sample template can be found at https://wa-biz-cfn.s3.amazonaws.com/wa_ent_net.yml.

Subnets

Required.

The subnets for this deployment.
Select at least 2 subnets in different availability zones. For a production environment, 3 private subnets are recommended.
Either private or public subnets need to be selected. Private and public subnets should not be mixed.

Number of subnets

Required.

The number of subnets chosen.

Load balancer scheme

Required.

  • Internet-facing — The load balancer is visible to public. Select this if you want the WhatsApp Business API service to be visible on a public endpoint.
  • Internal - The load balancer will not be reachable from outside of AWS. This scheme is preferred if you have your backend/CRM systems also hosted within AWS.

Note: If an internal scheme is chosen for the load balancer, configure private subnets for the load balancer. However, if an internet-facing scheme is chosen, configure public subnets for the load balancer. Failure to configure this properly results in the load balancer being inaccessible.

Load balancer subnets

Required.

For an internet-facing load balancer, select the public subnets from the VPC.
For an internal load balancer, select the appropriate private subnets.
Similar to other subnets, it's recommended you choose 3 subnets in different availability zones for the production environment.

Container Configuration

NameDescription

EC2 instance type

Required.

It's recommended choosing non-T2 instance types for production work loads.

Keypair to use

Required.

The appropriate key pair to access the EC2 instance, if required.

WA Enterprise container registry

Optional.

This is for future-proofing and to support experimental WhatsApp Business API clients. The default value should be good for a majority of cases.

WA Enterprise Client version

Required.

It's always recommended to use the latest stable version (see the changelog for the latest version).
Format: v2.yy.xx

The WhatsApp Business API client version always begins with a "v", unless explicitly stated otherwise. Using an incorrect version will cause stack creation failure.

EBS volume size

Required.

It's recommended choosing 16GB or more for production work loads.

Database Configuration

NameDescription

Store configuration in DB

Optional.

Enables storing configuration information in the database.
Options: true (default), false
Setting the value to false disables storing the configuration information in the database and stores it in files instead.

Existing DB hostname

Optional.

The existing database hostname
If you already have a dedicated MySQL database instance for the WhatsApp Business API client, you can enter the hostname here.
Leaving it empty will create a new RDS MySQL instance.

Storage capacity

Conditional.

Required if a database instance must be created by this template.
Enter the storage capacity required for the RDS in GB.

Instance type

Conditional.

Required if a database instance must be created by this template.
It's recommended choosing non-T2 instance types for production loads.

Administrator name

Required.

The administrator name for accessing the database.

Administrator password

Required.

The administrator password for accessing the database.

The database password should not contain any of these characters: ?{}&~!()^/"@

Server port

Required.

Port number to access the database backend.

DB Idle Connection Timeout

Optional.

The length of time in milliseconds after which the RDS closes idle connections
Default: 180000 ms

Storage type

Conditional.

Required if a database instance must be created by this template. For production loads, it's recommended to choose the General Purpose SSD (gp2) or Provisioned IOPS (io1) storage type.

Multi-AZ

Conditional.

Required if a database instance must be created by this template.
Enabling the Multi-AZ parameter turns on High Availability and failover support for the database instance.

IOPS

Conditional.

Required if a database instance must be created by this template.
This is only applicable if you also select the Provisioned IOPS (io1) storage type.

Engine version

Conditional.

Required if a database instance must be created by this template.

Logging Configuration

NameDescription

Logging driver for container logs

Optional.

Logging driver for the container logs.
Options: json-file (default), awslogs
The json-file value stores the logs on EC2 hosts. The awslogs value streams all container logs to CloudWatch.

Maximum container log file size

Optional.

The maximum size of a container log file in MB before it's rotated.

Maximum number of container log files

Optional.

The maximum number of log files to retain per container.
Stopped containers are eventually removed from the host. In those cases, all the retained log files for that container are deleted.

Days to retain CloudWatch logs

Optional.

Number of days to retain logs in CloudWatch.
Earlier this value was hard-coded in the template, but it is now made configurable. Select from one of the available values in the list.

Filesystem Configuration

NameDescription

File system identifier

Not used.

Leave this parameter empty.

Security Configuration

NameDescription

Key to encrypt DB & EFS

Optional.

By default, the AWS service key (the Default-Key option) is used to encrypt DB & EFS data at rest. Other options are:

  • Unencrypted: The data at rest is not encrypted
  • Create-New-Key: A new KMS key is created and used to encrypt the data
  • User-Provided-Key: You can provide a KMS key ID that is used to encrypt the data. Leave this blank, if another option is selected.

User provided key id

Optional.

You can provide a KMS key ID that is used to encrypt the data. Leave this blank, if the User-Provided-Key option is not selected.

DB connection encryption

Optional.

By default, the data in transit to the database is encrypted. This is currently only applicable for the Coreapp. Webapp encryption is not yet supported. In addition, with a new database engine, even if this option is disabled, the Coreapp performs encryption, but without server certificate (identity) verification.

CA certificate for DB connection

Optional.

The default value contains the RDS certificate bundle. If a non-RDS database is used, then the appropriate CA certificate bundle can be provided or you can leave it blank. The default value is adequate for enabling a secure connection with the database.

Client certificate for DB connection

Optional.

The client certificate for the database connection

Client key for DB connection

Optional.

The client key for the database connection

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 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
  • Database administrator name: Administrator name for the database connection

For security reasons, the database administrator password is not displayed.

Output Parameters

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: Set Shards

After the stack is created, you need to use the shards API call to increase the number of active Coreapp instances to match the value selected for Desired number of active 'coreapp' instances during stack creation.

Step 2: [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.

In AWS deployments, the SSL certificate is created using the load balancer hostname. If an IP address is used instead of the hostname for access, the warning will still be noticed.

WhatsApp will support configuring customer provided SSL certificates in a future release.

Step 3: 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.

If the phone number is capable of receiving text messages, use the SMS method for registration code retrieval.

If you have already received the registration code from WhatsApp, you can skip this step.

Step 4: Webhook Configuration

The configuration of WhatsApp Business API web callbacks and other parameters is described in the Application Settings documentation.

Refer to the Webhooks 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 4.

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.

You can expect about a minute or two of downtime.

Upgrading

It is highly recommended you backup your current application settings before uninstallation. Please follow the Backup and Restore documentation.

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, leave the Amazon S3 URL option selected and enter the appropriate WhatsApp Business API CFN template URL (e.g., for the WhatsApp Business API client: https://s3.amazonaws.com/wa-biz-cfn/wa_ent.yml).

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, leave the Use current template option selected, and 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.

Quick upgrade verification: Send a text message and verify that the API response contains the correct version number (i.e., the new version). Verify also that the message is received by the recipient.

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, leave the Amazon S3 URL option selected and enter the appropriate WhatsApp Business API CFN template URL (e.g., for the WhatsApp Business client: https://wa-biz-cfn.s3.amazonaws.com/wa_ent.yml). 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.

Rotating the RDS Certificate

If you enabled database connection encryption on the stack creation page, the connection between your Coreapp and the RDS instance is encrypted through a certificate that defaults to the certificate published by AWS RDS.

The previous 2015 AWS RDS certificate will expire on March 5, 2020. Follow the steps here to rotate the RDS Certificate for your WhatsApp Business API client.

Before you start, it is highly recommended to backup your current application settings and take a snapshot for your RDS instance. See the Backup and Restore documentation for more information.

  1. Ensure your EC2 instances are based on the latest AMIs listed below. If they are not, it’s likely your stack is created using the old CFN template that uses an old custom AMI. Upgrade your CFN template by following the instructions in the WhatsApp CFN template update section above.
    • ap-northeast-1: # Tokyo
      AMIID: ami-045f38c93733dd48d
    • ap-northeast-2: # Seoul
      AMIID: ami-06cf2a72dadf92410
    • ap-southeast-1: # Singapore
      AMIID: ami-0b4dd9d65556cac22
    • ap-southeast-2: # Sydney
      AMIID: ami-08bd00d7713a39e7d
    • eu-central-1: # Frankfurt
      AMIID: ami-04cf43aca3e6f3de3
    • eu-west-1: # Ireland
      AMIID: ami-0ff760d16d9497662
    • us-east-1: # N. Virginia
      AMIID: ami-02eac2c0129f6376b
    • us-east-2: # Ohio
      AMIID: ami-0f2b4fc905b0bd1f1
    • us-west-1: # N. California
      AMIID: ami-074e2d6769f445be5
    • us-west-2: # Oregon
      AMIID: ami-01ed306a12b7d1c96
  2. Ensure your EC2 instances have the latest RDS certificate bundle that includes both the old 2015 certificate and the new 2019 certificate.
    1. SSH into your EC2 instances. The certificates are located in /opt/certs/db-ca.pem.
    2. If needed, replace the existing certificates with the latest certificate bundle. The latest bundle can be downloaded with: 
      sudo wget https://s3.amazonaws.com/rds-downloads/rds-combined-ca-bundle.pem
    Note that if you can’t SSH into your EC2 instance, you can force the certificate update through EC2 instance replacement, which could cause some downtime. This assumes that when you created the stack, you were using the default rds-combined-ca-bundle.pem as the database connection CA certificate (This can be confirmed by checking the DBConnCA parameter in your stack through the AWS console). You’ll need to stop your current EC2 instance manually, then a new EC2 instance is deployed automatically in about 20 minutes. In this case, you can skip step 3.
  3. Restart all your WhatsApp Business API client containers. This can be done through the AWS console ECS service by stopping all tasks in your desired cluster. All tasks should be back in running state in less than 5 minutes. After that your WhatsApp Business API client should be using the latest certificate bundle and able to connect with both RDS instances in the old and new certificates.
  4. Update the RDS certificate on your RDS instances to the new 2019 certificate. See Updating Your CA Certificate by Applying DB Instance Maintenance in the AWS documentation for more information.

This software uses code of FFmpeg licensed under the LGPLv2.1 and its source can be downloaded here.