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.
Scale Your API Client With Multiconnect
The standard WhatsApp Business API Client solution runs on a single Docker container. In case you want to split the load and have multiple servers send and receive messages to WhatsApp, you can make use of our multiconnect solution on top of it.
The Multiconnect solution requires an existing high availability setup first. Follow the High Availability documentation to set it up, then continue below.
Overview
With high availability, only one Docker container is responsible for sending and receiving messages from WhatsApp servers. If messaging traffic exceeds the maximum throughput of a single Docker container, there will be a backlog of message sends and message delivery latency will increase. To scale out the WhatsApp Business API Client, multiconnect supports sharding to spread loads across multiple Docker containers. Currently, we only support static sharding with a shard number of 1, 2, 4, 8, 16, or 32. High availability is a special case of multiconnect where the shard number is 1.
In the cluster, there are two Coreapp nodes (CoreApp 1 and CoreApp 3) responsible for sending and receiving messages from WhatsApp server at the same time. Every message will only belong to one shard based on recipient ID.
Sharding
The WhatsApp Business API Client uses sharding to achieve multiconnect. Depending on the number of shards you set up, the database will store a shard map that determines which shard a message should go to depending on the recipient ID (or WhatsApp username). The function to determine this is:
shard_id = hash(recipient-id) % shard-number
Each shard is mapped to a running Docker container (Coreapp). The Webapp will know which Docker container to send the message request to based on the return of this function. It is recommended you set up shard number + X machines to be able to tolerate X machine failures.
In the 2 shard multiconnect diagram above, messages are routed to CoreApp 1 and CoreApp 3 based on the sharding function. CoreApp 2 is secondary — it is warm, but has no active connection to the WhatsApp servers. Assume CoreApp 1 gets messages for shard=0 and CoreApp 3 gets messages for shard=1. If CoreApp 1 dies, only messages for shard=0 will be affected. The system would still send and receive messages belonging to shard=1 using CoreApp 3. Similar to high availability, Master 1 will detect the failure of CoreApp 1 and failover shard=0 traffic to CoreApp 2. This failover will take approximately 35 seconds.
Setting Up Multiconnect
Once you have your cluster set up according to the High Availability documentation, use the following request to turn on multiconnect.
Remember you need to have shard number + X Docker containers of the Coreapp running before continuing.
Multiconnect does not guarantee High Availability. Have more Coreapps than shards running for High Availability.
Request
POST /v1/account/shards
{
"cc": "country-code",
"phone_number": "phone-number",
"shards": 1 | 2 | 4 | 8 | 16 | 32,
"pin": "pin",
"cert": "verified-name-cert-in-base64"
}
Parameters
| Name | Description |
|---|---|
| Required. Country code for the phone number registered for this WhatsApp Business API Client as a string. For example: |
| Required. Phone number registered for this WhatsApp Business API Client without the country code or plus symbol (+) as a string. For example: |
| Required. Number of shards you want to have as an integer. Options: |
| Optional. The existing 6-digit PIN for two-factor verification as a string. For example: |
| Required. With the introduction of the Populating this field allows Businesses to call this endpoint anytime. Before, businesses could only call this endpoint within 7 days of their phone number registration. A Base64-encoded certificate associated with the phone number previously specified. You can get this certificate using Business Manager. See Copy the Base64-encoded Certificate for information. Notes:
If the |
Response
201 Created : You successfully changed shard number 403 Forbidden : You could hit this if server is temporarily unavailable, retry the request should fix it
Retrieving Shard Information
Request
GET /v1/account/shards
Response
{
"account": {
"shards": number-of-shards
}
}
Message Send Rates
AWS Deployment Details
Template URLs:
- Enterprise: https://wa-biz-cfn.s3-us-west-2.amazonaws.com/wa_ent.yml?versionId=Tvb.Sa6uTwmvj1rSbbpKCmEKz2pyxcLG
- DB: https://wa-biz-cfn.s3-us-west-2.amazonaws.com/wa_ent_db.yml?versionId=3.vthzENa7qUOuZrozcX9hDk9n8.kdTg
- Lambda: https://wa-biz-cfn.s3-us-west-2.amazonaws.com/wa_ent_lambda.yml?versionId=gqIhZaXkX_NylKaPJMDBlQNk9.Pl_34b
- Network: https://wa-biz-cfn.s3-us-west-2.amazonaws.com/wa_ent_net.yml?versionId=Y_NczQaJ.4QTAlyedZPir2XF_IAPDpsh
The template allows you to configure the number of active Coreapp container instances to be created. The template creates one additional Coreapp container instance to aid quick switchover in case of Coreapp failure.
The template creates the following number of instances per environment type for Multiconnect, by default, when High Availability is enabled:
- Production: EC2 instances: 3, Web container: 3, Coreapp container: 3, Master container: 3
- Staging: EC2 instances: 2, Web container: 2, Coreapp container: 2, Master container: 2
The template is configured to auto scale EC2 instances depending on the memory utilization. Memory utilization increases (or decreases) with an increase (or decrease) in number of “active” Coreapp container instances. Hence, when more Coreapp instances are created, EC2 instances auto-scale accordingly. However, maximum number of EC2 instances that can be created is capped as follows:
| Active Coreapp Instances | Maximum EC2 Instances |
|---|---|
2 | 3 |
4 | 4 |
8 | 5 |
16 | 8 |
32 | 15 |
RDS Instance Sizing
API request rate & number of active Coreapp instances determine number of connections to the database. With 8 active Coreapp instances and an API rate of 100 messages/second, it requires about 700 DB connections (SSL is disabled) and 1200 DB connections (when SSL is enabled). However, with 32 active Coreapp instances and an API rate of 250 messages/second, it requires about 1,700 DB connections.
In the current release, we used db.m4.2xlarge for 8 active Coreapp instances (DB connection encryption disabled) and db.m4.4x.large for 32 active Coreapp instances (DB connection encryption enabled). The following table provides a guidance on RDS instance class selection and the number of maximum connections it can support:
| RDS Instance | Maximum DB Connections |
|---|---|
| 318 |
| 636 |
| 1272 |
| 2543 |
| 1212 |
| 2424 |
| 4848 |
| 9696 |
| 19391 |
| 38783 |
| 636 |
| 1272 |
| 2543 |
| 5086 |
| 12716 |
| 20345 |
| 298 |
| 596 |
| 1192 |
| 2384 |
Configuration
- Active Coreapp instances set in a template only govern the number of Coreapp instances created. However, to activate the same, Set Shards (documented in the Setting Up Multiconnect section) must be used. Default value of shards is 1.
- Always ensure that the number of Coreapp instances is always greater than or equal to the shard number set in the API.
- To increase the number of shards:
- Create or update the stack with desired number of active Coreapp instances.
- Once successful, use Set Shards to activate the same number of active Coreapp instances/shards.
- Note: Set Shards causes all Coreapp container instances to stop and be restarted automatically. There will be a downtime of about 45 seconds to 1 minute when Set Shards is executed.
- To decrease the number of shards:
- Use Set Shards to reduce the same number of active Coreapp instances/shards.
- Once all the Coreapp instances restarts successfully, update the stack with the same number of active Coreapp instances.
- Note: Updating the stack might terminate currently active Coreapp instances that are serving the shard. However, other alive Coreapp instances will be assigned shortly. In other words, there could be an additional downtime (~35 seconds) during this procedure.