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.
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:
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 a new AWS template that we have tested for higher and more stable messaging throughput. If you are looking for the older AWS template, see AWS Archive.
Before you start you will need to:
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.
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.
The WhatsApp Business API client makes use of a CentOS 9 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 9 AMI image:
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:
Depending on initial testing, WhatsApp will determine whether we can provide an alternate option that is available in all regions.
No, we don't support KOPS. We do support the AWS solution based on ECS. We also have a general Kubernetes minikube 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.
To deploy the network template:
Name | Description |
---|---|
| Required. Name of the stack to be created. |
Name | Description |
---|---|
| Required. The availability zones (AZs) for creating the VPC. |
| Required. The number of availability zones selected. |
Name | Description |
---|---|
| Required. The IP address range (CIDR) for this VPC. |
| Required. The VPC tenancy |
Name | Description |
---|---|
| Required. The IP address range (CIDR) for public subnets |
| Required. The IP address range (CIDR) for public subnets |
| Optional. Required if the number of availability zones is greater than 2. |
| Optional. Required if the number of availability zones is greater than 3. |
Name | Description |
---|---|
| Required. Options: |
| Conditional. Required if the private subnet creation is set to |
| Conditional. Required if the private subnet creation is set to |
| Conditional. Required if the private subnet creation is set to |
| Conditional. Required if the private subnet creation is set to |
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.
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:
Name | Description |
---|---|
| Required. The name of the stack to be created. The stack name must be less than or equal to 22 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 |
Name | Description |
---|---|
| Optional. Enables the High Availability feature. Default: |
| Required. Number of messages you wish to send per second. Together with the |
| Required. The dominant message type you wish to send and receive. Together with the |
| Optional. Installs node-exporter on each CoreApp host for instance monitoring purposes. Default: |
Name | Description |
---|---|
| Required. The name of the network CloudFormation stack created by the network setup step. |
| Required. The number of subnets chosen. Currently we only support 2 subnets for deployment to distribute the ECS tasks evenly on all hosts. |
| Required. Currently we only support Internet-facing load balancers, which are visible to the public. Please modify the security groups after the API stack is created to close off unnecessary access. |
Name | Description |
---|---|
| Required. The appropriate key pair to access the EC2 instance, if required. |
| 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. |
| Required. It's always recommended to use the latest stable version (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. |
| Required. It's recommended choosing 32GB or more for production work loads. |
Name | Description |
---|---|
| Optional. Enables storing configuration information in the database. |
| Optional. The existing database hostname. |
| Required. The administrator name for accessing the database. |
| Required. The administrator password for accessing the database. The database password should not contain any of these characters: ?{}&~!()^/"@ |
| Required. Port number to access the database backend. |
| Optional. Indicates whether to persist Database connection for Web containers. Default: |
| Optional. The length of time in milliseconds after which the database closes idle connections. |
Name | Description |
---|---|
| Optional. The logging driver for the container logs. |
| Optional. The maximum size of a container log file in MB before it's rotated. Allowed values between 1 and 250 (both inclusive). Default: 50. |
| Optional. The maximum number of log files to retain per container. Allowed values between 1 and 30 (both inclusive). Default: 7. |
| Optional. Number of days to retain logs in CloudWatch. Default: |
Name | Description |
---|---|
| Not used. Leave this parameter empty. |
Name | Description |
---|---|
| Optional. By default, the AWS service key (the Default-Key option) is used to encrypt DB & EFS data at rest. Other options are:
|
| 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. |
| 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. |
| 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. |
| Optional. The client certificate for the database connection |
| Optional. The client key for the database connection |
These parameters are required for Grafana dashboards to retrieve application metrics for monitoring purposes.
Name | Description |
---|---|
| Required. Specifies the WhatsApp Business API Username. |
| Required. Specifies the password for |
Name | Description |
---|---|
| Required. Specifies the password that is used as the login password for the Grafana dashboard when the stack is created. |
| Optional. Indicates whether SMTP is enabled for setting up email alerts. Valid values are: Default: |
| Optional. The SMTP host used in email alerts. For instance, smtp.gmail.com:465. |
| Optional. Specifies the SMTP user name used in email alerts. |
| Optional. Specifies the SMTP password used in email alerts. |
Upon successful creation of template, the following parameters are displayed:
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.
"<stackName>-ms-xxx-EcsSecurityGroup"
to restrict SSH access for the monitoring stack.
Once the WhatsApp Business API client is successfully deployed, it needs to be configured to bring it into operation.
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.
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.
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" } }
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.
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.
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):
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.
Updating a CloudFormation stack directly may result in the database to be destroyed and recreated. We highly recommend you to follow the manual steps in the next section to update the system to avoid loss of data.
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:
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.
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.
Important: Please be reminded that there will be downtime. Estimated downtime may be 5 to 15 minutes. Please make sure that you have all DevOps best practices followed, such as application settings backup and database backup.
2
.c5.large
.
c5.large
, then choose Create template version.
r5.xlarge
.
3
.3
.2
.2
.2
.