Architecture and Security
This document explains the WhatsApp Business API Architecture and Security.
Last updated
Was this helpful?
This document explains the WhatsApp Business API Architecture and Security.
Last updated
Was this helpful?
Was this helpful?
The Cloud API architecture significantly simplifies the BSP’s operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings).
For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments:
With Cloud API, BSPs or direct clients do not need the WebApp and CoreApp containers that are used in the On-Premises product. Meta will manage all database data and media data on behalf of the BSP or direct client.
As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.
Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.
With the Cloud API, every WhatsApp message continues to be protected by Signal protocol encryption that secures messages before they leave the device. This means messages with a WhatsApp business account are securely delivered to the destination chosen by each business.
The Cloud API uses industry-standard encryption techniques to protect data in transit and at rest. The API uses Graph API for sending messages and Webhooks for receiving events, and both operate over industry standard HTTPS, protected by TLS.
See Encryption Overview whitepaper for additional details.
Local Storage for Cloud API numbers is available. This gives businesses the option to control the location where their message data is stored at rest. If your company operates in a regulated industry such as finance, government, or healthcare, you may prefer to have your message data stored in a specific country when at rest because of regulatory or company policies.
The following message flows are covered by Local Storage feature:
Outgoing messages: messages you are sending to recipients with Cloud API
Incoming messages: messages you are receiving back via Cloud API
The following message types are covered by Local Storage feature:
Text messages: textual payload (message body) is localized
Media messages: media (audio, document image or video) payload is localized
Template messages: components with text / media payload are localized
Also, a limited set of metadata attributes is included in the localized data set, in order to correctly associate encrypted localized message payload with the originally processed message and to audit the fact of localization. Metadata is protected with tokenization and encryption.
The following regions are currently supported by Cloud API Local Storage:
APAC: India, Singapore, Indonesia, South Korea, Japan, Australia
LATAM: Brazil
MEA: South Africa, Bahrain
Europe: EU (Germany), UK, Switzerland
NORAM: Canada
Migration risks and Downtime
There are no migration risks. This is a similar process as migrating from On-Premise API to Cloud API, and the downtime is typically less than 5 minutes and no re-verification of the business phone number is required.
If you wish to change the local storage of a WABA please reach out to our Support Team with the specific location. You will need to receive a pin code in the phone number to confirm the change to local storage.
With such settings enabled, Cloud API uses a localized storage in the specified country for persisting message content, instead of using its default storage based in the US. Alternatively, by disabling Local Storage, Cloud API reverts to its default storage based in the US.
When a user sends a message to one of these businesses, the message travels end-to-end encrypted between the user and the Cloud API. As per the Signal protocol, the user and the Cloud API, on behalf of the business, negotiate encryption keys and establish a secure communication channel. WhatsApp cannot access any message content exchanged between users and businesses.
Once a message is received by the Cloud API, it gets decrypted and forwarded to the Business. Messages are only temporarily stored by the Cloud API as required to provide the base API functionality.
Messages from a business to a user flow on the reverse path. Businesses send messages to Cloud API. The Cloud API service stores the messages temporarily and takes on the task to send the message to the WhatsApp platform. Messages are stored for any necessary retransmissions.
All messages are encrypted by the Cloud API before being sent to WhatsApp using the Signal protocol with keys negotiated with the user (recipient).
WhatsApp acts as the transport service. It provides the message forwarding software; both client and server. It has no visibility into the messages being sent. It protects the users by detecting unusual messaging patterns (like a business trying to message all users) or collecting spam reports from users.
Cloud API, operated by Meta, acts as the intermediary between WhatsApp and the Cloud API businesses. In other words, those businesses have given Cloud API the power to operate on their behalf. Because of this, WhatsApp forwards all message traffic destined for those businesses to Cloud API. WhatsApp also expects to receive from Cloud API all message traffic from those businesses. This is the same client behavior that the On-Premise client has.
WhatsApp gives Cloud API metering and billing information for the Cloud API businesses. It does not share any other messaging information.
Meta, in providing the WhatsApp Cloud API service, acts as a Data Processor on behalf of the business. In other words, the businesses have requested Meta to provide programmatic access to the WhatsApp platform.
Cloud API receives from WhatsApp the messages destined for the businesses that use Cloud API. Cloud API also sends to WhatsApp the messages sent by those businesses. Other parts of Meta (other than Cloud API) do not have access to the Cloud API business communications, including message content and metadata. Meta does not use any Cloud API data for advertising.
All data collected, stored and accessed by Cloud API is controlled and monitored to ensure proper usage and maintain the high level of privacy expected from a WhatsApp client.
Information about the businesses, including their phone numbers, business address, contacts, type, etc. is maintained by Meta and the Business Manager product and is subject to the terms of service set by Meta. Cloud API relies on Business Manager and other Meta systems to identify any access to Cloud API on behalf of the business.
Messages sent or received via Cloud API are only accessed by Cloud API, no other part of Meta can use this information. Messages have a maximum retention period of 30 days in order to provide the base features and functionality of the Cloud API service; for example, retransmissions. After 30 days, these features and functionality are no longer available.
Cloud API does not rely on any information about the user (customer/consumer) the business is communicating with other than the phone number used to identify the account. This information is used to deliver the messages via the WhatsApp client code. User phone numbers are used as sources or destinations of individual messages; as such they are deleted when messages are deleted. No other part of Meta has access to this information.
No message content is shared or sent to WhatsApp at any time and no WhatsApp employee has access to any message content.
Message content
Cloud API
No
No
Consumer phone number
Cloud API
No
Yes
Non-identifiable statistics
Cloud API
Yes
Yes
Integrity signals - per business
WhatsApp Client
No
Yes
Business information
Business Manager
Yes
Yes
Billing - per business
Yes
Yes
Meta enables businesses to fulfill their obligations under the General Data Protection Regulation (GDPR). However, it's important to note that each business bears the responsibility of ensuring its own compliance with the GDPR, similar to other applicable laws.
To understand compliance with GDPR, please see:
As announced in November 2023, Meta is transitioning to a fully Cloud-hosted WhatsApp Business Platform and will stop supporting On-Premise API in October 2025.
Starting from On-Premise client v2.53, all new feature updates will be exclusively delivered to Cloud API. While the On-Premise API client will receive quarterly releases, they will focus solely on bug fixes and security patches. From May 15, 2024, 360dialog will not allow for new numbers to be onboarded with On-Premise API. We will continue supporting already registered On-Premise API throughout 2024, but we strongly recommend to start changing the hosting type of numbers to Cloud as soon as possible. Learn here how to integrate with Cloud API.
Unlike typical REST APIs, the WhatsApp (WA) Business API requires the WhatsApp Business API Client to be installed and managed. As an official WhatsApp Business Solutions Provider - we (the Business Solutions Provider) will do this installation, hosting and maintenance for you. When it is up and running, the WhatsApp Business API client can communicate with WA servers in an end-to-end-encrypted manner and you integrate with this system using our API endpoints.
The WhatsApp Business API Client consists of a set of Docker containers, as well as database and media volumes as shown in the following image.
A WhatsApp Business API Client consists of the following components shown in the preceding image.
WebApp node Handles authentication and authorization of WhatsApp Business API users Accepts incoming Rest API calls from your business systems and forwards them to the CoreApp node(s)
CoreApp node(s) - Receives Rest API calls from the WebApp node, and sends resulting messages to the WhatsApp server. - After receiving messages from the WhatsApp server, sends messages to your Webhook server that include the incoming payload from the WhatsApp servers. - Downloads and saves media to the media volume
Database Stores data for the WhatsApp Business API client, including messages, contacts, configurations etc.
Media volume Stores uploaded media files used for outgoing media messages / media message templates, as well as the media files from incoming media messages
WebHook server - Receives incoming HTTP messages from the CoreApp nodes
After the successful setup of the WhatsApp Business API Client you will get an API-KEY. Then your business can start integrating with the WhatsApp Business API like common REST APIs via HTTPS, and receiving incoming messages using Webhooks.
Messages are encrypted between the WhatsApp app on a user’s smartphone through the WhatsApp infrastructure / data centers until it reaches our hosted Docker containers (described above). Only in these containers the decryption takes place. The Docker containers are installed in a redundant and multi-connect environment.
After sending, the messages are processed to the WhatsApp Business container where they are encrypted and dispatched into the WhatsApp infrastructure and finally pushed to the targeted device, where it is decrypted.
At any given time, you can only have one instance of the WhatsApp Business API Client running for a single phone number.
When using the WhatsApp Business API, we will always have in effect and maintain administrative, physical and technical safeguards that: (a) meet or exceed industry standards, (b) are compliant with applicable Laws (including data security and privacy laws, rules and regulations), and (c) are designed to prevent any unauthorized access, use, processing, storage, destruction, loss, alteration or disclosure of User Data.
We make use of the below Safety features as provided by WhatsApp.
Passwords and Authentication All requests to the WhatsApp API must be authorized with an API-KEY. Please refer to the API documentation for more information about this topic.
SSL Configuration Access to the WhatsApp Business API client requires HTTPS. The WhatsApp Business API Client generates a self-signed certificate by default when it is created. As Webhooks also requires HTTPS for callbacks.
Network Segregation We host the Webapp and Coreapp nodes in separate, segregated networks, and expose them only to required services.
Message Encryption See WhatsApp Encryption Overview technical whitepaper for more detail
We act as a data processor on behalf of our Integration Partners, and the Integration Partner on behalf of the Businesses' using the WhatsApp Business API. We will only process data to and from the WhatsApp Business Solution according to the instructions of Businesses as communicated through WhatsApp API or by their Integration Partner. By using our services, both Parties commit to their compliance with all applicable privacy laws and regulations.
Integration Partners must sign a Data Processing Agreement which outlines the specifics prior to using our API.
The General Data Protection Regulation (GDPR) creates consistent data protection rules across Europe. It applies to companies (regardless of where they are based) who process personal data about individuals in the EU.
If you have specific questions about our On-Premise Data Processing Policies or GDPR, please reach out to: [email protected]
