Prerequisites

Before you can use Amazon Web Services (AWS) to deploy the WhatsApp Business API, you must set up the following:

Setting 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.

Creating 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 with which you will be deploying the WhatsApp Business API.

Subscribing 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.

Deployment

Deployment is categorized into three areas:

Step 1: 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 network infrastructure on AWS.

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

Network Requirements

  1. 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.
  2. 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:

  1. Go to the CloudFormation console for your region (for example, eu-west-1).
  2. Select Create a stack.
  3. Choose Specify an Amazon S3 template URL, and enter https://s3.amazonaws.com/wa-biz-cfn/wa_ent_net.yml, or click

    Deploy Template

    and choose the appropriate region, if needed, from upper right corner of the webpage.
    Select Template

Parameters

NameRequiredDescription

Stack name

Yes

Name of the stack to be created

Availability Zones Configuration

Availability zones

Yes

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

Number of availability zones

Yes

Enter the number of availability zones selected.

VPC Configuration

IP address range

Yes

Enter the IP address range (CIDR) for this VPC.

Tenancy

Yes

Select VPC tenancy here: default or dedicated.

Public Subnet Configuration

IP range - subnet #1

Yes

Enter the IP address range (CIDR) for public subnets.

IP range - subnet #2

Yes

IP range - subnet #3

No

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

IP range - subnet #4

No

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

Private Subnet Configuration

Create private subnets?

Yes

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

IP range - subnet #1

Conditional - Yes

Required, if the private subnet creation is set to true.

IP range - subnet #2

Conditional - Yes

Required, if the private subnet creation is set to true.

IP range - subnet #3

Conditional - No

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

IP range - subnet #4

Conditional - No

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

Step 2: Database (RDS - MySQL) Setup (optional)

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.

WhatsApp Business API client uses the database (RDS - MySQL) to store information required for the functioning of 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 already existing database 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:

  1. Go to the CloudFormation console for your region (for example, eu-west-1.
  2. Select Create a stack.
    Create Stack
  3. Choose Specify an Amazon S3 template URL, and enter https://s3.amazonaws.com/wa-biz-cfn/wa_ent.yml, 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.
  4. You will then be able to enter parameters. Refer to the table below for parameter descriptions.
    Enter Parameters

Parameters

NameRequiredDescription

Stack name

Yes

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

Environment type

Yes

  • Production — Resources appropriate for a production environment is used. For example, EBS volume will be 16GB/SSD, RDS will use SSD disks, and MultiAZ is enabled.
  • Staging — Resources appropriate for a staging environment is used. For example, EBS volume will be 10GB/SSD, RDS will use magnetic disks, and MultiAZ is disabled.

High Availability

No

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

Desired number of active 'coreapp' instances

No

Default: 2
The number of desired active coreapp instances. This needs to be complemented with "Set shards" API to increase the number of active coreapp instances.

Network configuration

VPC

Yes

Select 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://s3.amazonaws.com/wa-biz-cfn/wa_ent_net.yml.

Subnets

Yes

Please select at least 2 subnets in different availability zones. For 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

Yes

Enter the number of subnets chosen.

Load balancer scheme

Yes

  • Internet-facing — The load balancer will be 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.

Load balancer subnets

Yes

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

Container configuration

EC2 instance type

Yes

For production work loads, it's recommended to choose non-T2 instance types.

Keypair to use

Yes

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

WA Enterprise container registry

No

This is for future proofing to support experimental WA Business API Clients. The default value should be good for majority of cases.

WA Enterprise Client version

Yes

It's always recommended to use the latest stable version. The format for version numbers is v2.yy.xx (see the changelog for the latest version).

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

Database configuration

Store configuration in DB

No

Default: true
Setting the value to false disables the configuration information to be stored in Database and will continue to be stored in files.

Existing DB hostname

No

If you already have a dedicated database (MySQL) 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 RDS in GB.

Instance type

Conditional

Required if a databas instance must be created by this template. For production loads, it's recommended to choose non-T2 instance types.

Administrator name

Yes

Administrator name to access the database

Administrator password

Yes

Administrator password to access the database

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

Server port

Yes

Port number to access the database backend

Logging configuration

Logging driver for container logs

No

Default: json-file

Logging driver for container logs. Default value stores the logs on EC2 hosts. Other option is "awslogs", which streams all container logs to CloudWatch

Maximum container log file size

No

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

Maximum number of container log files

No

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 will be lost.

Days to retain CloudWatch logs

No

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

Filesystem configuration

File system identifier

No

Not used. Please leave this parameter empty.

Security Configuration

Key to encrypt DB & EFS

No

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

  1. Unencrypted: Data at rest is not encrypted
  2. Create-New-Key: A new KMS key is created and used to encrypt the data
  3. User-Provided-Key: User can provide a KMS key ID, which will be used to encrypt the data. Leave this blank, if other option is selected.

User provided key id

No

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

DB connection encryption

No

By default, data in transit to database is encrypted. This is applicable for the Coreapp only at this point. Webapp encryption is not supported yet. 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

No

Default value contains the RDS certificate bundle. If non RDS database is used, then appropriate CA certificate bundle can be provided or leave it blank. Default value is adequate to enable secure connection with DB.

Client certificate for DB connection

No

Client certificate for database connection.

Client key for DB connection

No

Client key for database connection.

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.

Output after Deployment

Upon successful creation of template, the following parameters will be output:

  • Load balancer name: Hostname of the load balancer to access 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 Busines API Client Configuration

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

Step 1: SSL Configuration (optional)

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 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 HTTPS Setup 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 2: Database Configuration

This step is no longer required if you are using the CloudFormation template release 2.1.0 or higher. This will be done automatically during the setup.

The WhatsApp Business API client must be configured to use the MySQL database before proceeding with other configuration steps.

Request

curl -d @path-to-payload/payload.json 
  https://load-balancer-hostname-or-ip/api/control.php

With the configuration payload (JSON format):

{  
   "payload":{
      "set_settings": {
        "database_engine":"MYSQL",
        "mysql":{  
           "hostname": "your-database-hostname-domain",
           "port": your-port,
           "username": "your-db-admin-username",
           "password": "your-db-admin-passowrd"
        }
     }
	}
}

Response

{"meta":{"waent version":"v2.xx.yy"},"payload":{},"error":null}

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 section 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 messagea, 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 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 message, the WhatsApp Business API client will POST the message status/details to the Webhook configured earlier.

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

Restarting the Coreapp and Webapp

To restart the application, go to 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 will stop both the Webapp and CoreApp. Shortly, the AWS Infra will restart both the Webapp and CoreApp.

Expect about a minute or two of downtime.

Upgrading the WhatsApp Business API Client

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

Note: You can upgrade the CFN template URL and the WhatsApp Business API client version at the same time. In step 5 below, instead of selecting Use current template, 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://s3.amazonaws.com/wa-biz-cfn/wa_ent.yml).

  1. Go to the CloudFormation (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 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 the WhatsApp team. 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 update

  1. Go to the CloudFormation (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. On 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://s3.amazonaws.com/wa-biz-cfn/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 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.