On-Premises API FAQs

WhatsApp considers communications with Business API users who manage the API endpoint on servers they control to be end-to-end encrypted since there is no third-party access to content between endpoints.

Some organizations may choose to delegate management of their WhatsApp Business API endpoint to a third-party Solution Partner. In these instances, communication still uses the same Signal protocol encryption. However, because the WhatsApp Business API user has chosen a third party to manage their endpoint, WhatsApp does not consider these messages end-to-end encrypted.

In addition, if you are using HTTPS when making calls to the WhatsApp Business API client, that data is SSL-encrypted (from your backend client to the WhatsApp Business API client).

See our WhatsApp Encryption Overview technical whitepaper for more detail.

No, you can run a single account per instance. If you need a second test account make sure to use a different number for that second instance.

NO! At any given time, you can only have one instance of the WhatsApp Business API Client running for a single phone number. As soon as you register a second instance, your first instance will get kicked off and fail. We are working on a proper solution that will allow you to accomplish this. We will keep you posted of any updates.

The WhatsApp Business On-Premises API Client requires a database to stores keys to decrypt messages sent between a business and customers. All messages on WhatsApp are encrypted with sender and receiver keys. Customer keys are stored on their mobile device and business keys are stored in the business' database. Learn more about WhatsApp's Security.

The WhatsApp Business Cloud API is an alternative wherein Meta hosts a business' database. The Cloud API allows you to implement WhatsApp Business APIs without the cost of hosting of your own servers. Learn more.

No. There's currently no way to run multiple numbers in the same WhatsApp Business API client setup. We are working on a proper solution that will allow this in the future.

Yes, Whatsapp Flows can be sent with On-Premises API. You can learn more about Whatsapp Flows here, or learn how to get started with Whatsapp Flows and On-Premises API here.

Yes! See Set Up and Debug Your Network, Ports.

No. The WhatsApp Business API Client opens an outbound TCP connection to port 5222 or 443 on the WhatsApp servers. TCP traffic occurs over this long-lived connection. Normally firewalls classify this as allowing “outbound traffic and the established traffic.” Of course, packets will flow back and forth once the connection is established but the connection start comes from the WhatsApp Business API Client so there is no need for a rule allowing inbound connections.

Requirements depend on your load and situation. The solution will run on any internet-connected machine that runs docker. For instance, simple testing can be done on a laptop.

For single-instance production server setup, we recommend at least 250 GB SSD, 16 GB RAM, and 4 core CPU. HDD is not recommended as the I/O speeds will become bottlenecks under load.

For Multiconnect production server setup, we recommend at least 50 GB SSD, 4 GB RAM and 2 core CPU for each Coreapp/Master/Webapp container.

In most cases you should run the database on a separate physical server from the core and web containers. The database server should only be a few milliseconds of latency away from the compute machine(s).

This setup supports sending approximately 20 messages per second.

MySQL 5.7.x, MySQL 8.0.x, PostgreSQL 13.x, 12.x, 11.x are required. Using a previous version will throw an Unable to initialize config store error.

Set up MySQL locally using Docker by following the Docker MySQL guide.

Set up PostgreSQL locally using Docker by following the Docker PostgreSQL guide.

In most cases you should run the database on a separate physical server from the core and web containers. The database server should only be a few milliseconds of latency away from the compute machine(s).

An allowlist can be created with either hostnames or IP addresses.

See the Hostnames section of the Network Requirements documentation for more information.

Yes, the TCP connection is necessary. If your business cannot open additional ports, you can use terminated SSL.

See the Network Requirements documentation for more information.

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

MySQL and PostgreSQL are supported. If you run Docker by yourself, you must provide a MySQL/PostgreSQL database for the containers to connect to. Using the AWS template sets up a MySQL database by default.

See Get Started, Environment for information.

You can restart the Docker containers by running the following code:

Coreapp Docker container

docker restart wacore<Current_WABA_Version>

Webapp Docker container

docker restart webapp<Current_WABA_Version>

You can check which version you're running with

docker ps

Yes, log rotation for webapp containers and coreapp containers has slightly different behaviors:

• Webapp: the last 30 log files will be retained. The log file is rotated only if its size is greater than 20MB.
• Coreapp: the last 30 log files will be retained. The log file is rotated only if its size is greater than 15MB. Rotated files are compressed.

There is a script that can be triggered externally to clean up old logs of a container:

docker exec CONTAINER_NAME /opt/whatsapp/bin/cleanup.sh

The script works with both webapp and coreapp containers. By running the script, old log files will be removed so that only 30 log files of the container remain.

Your system might start slowing down as the space fills up. This can be caused by many media files, messages, and large log files. Log files are automatically rotated, but if they start to get large, deleting them is safe.

Messages are stored in the database. You can delete messages as necessary. Also, if the pass_through is set to false in the application settings, then all messages are saved in the database until they are explicitly deleted.

Media files that users send to you are downloaded to the media volumes. It is up to the business to decide which media files to delete, but it is generally safe to delete any media files. You can use docker inspect your-container-id to check where the media volume folder is.

Yes, the database can be used in other ways without touching the WhatsApp related tables.

The database tables store information related to app settings, chat threads, messages, media, etc., which are all required by the app to operate.

v2.25.x improves outbound and inbound performance over previous releases. This optimization relies on creating additional database connections. For some deployments, this can cause the number of database connections to increase and reach configured limits. To keep the increased performance, you can increase the maximum number of connections your database server can accept. If that's not possible, you can change the the axolotl_context_striping_disabled parameter to disable this behavior. See the Applications Settings documentation for more information on how to do this change.

Database garbage collection periodically cleans up the messages and messages_reciept_log tables to help with database management.

The garbage collector retains certain messages to allow for successful delivery/processing. For example, retaining incoming message for a certain period of time to allow business integrations to mark the message as read.

The Coreapp performs garbage collection at random intervals (i.e., every few hours). This is to prevent potential performance degradation in High Availability stacks due to database contention.

Garbage collection is independent of the callback queue. For example, if the Webhook server isn't available for 4 days, the callbacks will be stored to be delivered when the Webhook server connectivity is restored.

Use the database garbage collection services API endpoint to purge messages and corresponding message receipts from the messageStore.messages and messageStore.messages_receipt_log tables.

If you back up your current setup and restore it on the new machine, the registration information should move over with the rest of your implementation. See the Backup and Restore Settings documentation for more information.

Logging a user out via the users endpoint will invalidate all of the auth tokens assigned to that account. Deleting a user will have the same effect, though that's much more drastic. Keep in mind that logging a user in via the users endpoint will return a new auth token, but it will not invalidate auth tokens already in circulation for that user. Anyone in possession of a previously provisioned token will continue to be able to use it until it expires or is invalidated via one of the previously mentioned methods.

Note: Please do not send the same message repeatedly to the same recipient using the WhatsApp Business API.

There can be multiple reasons why delivery rates are not 100%. Some common cases include users having sporadic access to network, being inactive for a period of time, or to create a high quality user experience.

Messages that can be delivered with WhatsApp will have a very high delivery rate. However there are many reasons why a message may not be delivered. You will have access to the exact status of a message by monitoring your callbacks. This is different from sending messages with SMS, for example, where you do not have access to final delivered status and resending the message may indeed produce a different outcome.

Messages may remain undelivered because a user's phone is out of service, or battery, or they have lost it and are getting a new one and have disabled their SIM. It is possible there are errors in the business client's ability to connect to the network. It is also possible callbacks (Webhooks) are not being delivered. You can monitor these situations by using the health node. You can turn on server receipt callbacks to know that the message made it into the WhatsApp server cloud.

If and when a user does reconnect to the network all the messages you sent will be delivered to them. Receiving more than one message with the same content will be a bad experience for them. They will be more likely to block you or complain. You will be more likely to be banned.

If you send a message and receive a message ID from the API, you have done what you can to send this message. Do not resend the same content to the same recipient.

If you are seeing low delivery rates over a prolonged period of time, please file a support ticket with Direct Support.

When you send a message, as soon as you get back a message ID, that means the message request has been stored on the database. The WhatsApp Business API Client will keep attempting to send that message until acknowledged by the WhatsApp server. This process has no end timeline. The WhatsApp server will then try to deliver that message to the user's phone. If the user's phone is not online, the message will be stored for 30 days before being discarded by the WhatsApp server.

Currently, there is no way to see how many or which users have blocked your business. The best indicator would be to listen for status callbacks and if you do not receive the delivered status, then either the user has blocked your business or they do not have a network connection. See the Webhook documentation for more details.

If a user has blocked your business, the Contacts API will continue to return that phone number as a valid WhatsApp user. However, when you send the message, it will never get delivered. If it is a paid message, you will not be charged.

In the normal consumer scenario, this is by design when the sender is not in your address book and you have not sent a message to this sender in the past. In the enterprise scenario, a business should use Message Templates when first engaging a user to establish "trust"; in doing so, the WhatsApp Business API Client will then abide by the in-app auto-download setting.

In the normal consumer scenario, this is by design when the sender is not in your address book and you have not sent a message to this sender in the past. In the enterprise scenario, a business should use Message Templates when first engaging a user to establish "trust"; in doing so, the WhatsApp Business API Client will then be able to render the link and make it clickable.

Absolutely! Reach out to your WhatsApp representative and make this request.

No, the order in which the messages arrive is not guaranteed to be the same order as what was sent. If ordering is critical to your use case, the suggested approach is to listen for the delivered callback of the first message before firing the second message.

When using the messages node, you need to set the Content-Type header to application/json for the WhatsApp Business API Client to properly parse the message body. There is also an Authorization header that needs to be set and must contain an unexpired access token. See the Login and Authentication documentation for information on how to get your token and when it expires.

Yes, send an API call to the contacts node before sending a message. The information from checking contacts is cached in the container and not doing this might result in an Unkown Contact error. See the Check Contacts documentation for more information.

If there is a delay in a subset of numbers, then it is likely not an issue affecting the customers integration but rather an issue on the recipients end, these delays in delivery can happen for a number of reasons. See Send Message Performance, Delays for more information.

No this is not possible. Numbers that are registered under WABAs (WhatsApp Business Accounts) can only message regular WhatsApp accounts.

There is no cleanup mechanism for either outgoing nor incoming media files. You may delete your media files manually by locating them on your file system.

To find the mountpoint of your media volume, you can run a docker command.

Request

docker volume inspect whatsappMedia

Response

[
    {
        "Driver": "local",
        "Labels": {},
        "Mountpoint": "/var/lib/docker/volumes/whatsappMedia/_data",
        "Name": "whatsappMedia",
        "Options": {},
        "Scope": "local"
    }
]

Then, to see all your incoming media files you can run the ls command with the received Mountpoint file path:

ls /var/lib/docker/volumes/whatsappMedia/_data/

For AWS setup, the media volume is mounted to /mnt/wa/media path on the host.

The maximum file upload size is 64 MB, which means this limit also applies to any image, document, or video you send with a message.

It is up to you when to delete media.

After uploading media, you will receive a media ID, which you can use to send a message that includes the uploaded media element. Upon sending the media message, the WhatsApp Business API will encrypt and upload the media to WhatsApp servers where it will remain for a period of 14 days. After that, you can decide to delete the media by providing the media ID or to keep it for later use. While we recommend keeping the media for 30 days, it is up to you to decide the retention policy based on your business's policy or use-case.

For images, the caption will be added as description. The caption text appears in full length for images on both Android and iPhone.

For documents, the caption replaces the filename. It is not meant to be displayed on the user's device as description text but instead to show the name of the file. iPhones show the full text while Androids truncate the filename; this is technical limitation of the current implementation of WhatsApp on both devices.

When sending image as an album from the WhatsApp Business API, you will need to send at least 4 images in succession. If the user's conversation view is currently active when the images are received, then the album view is unavailable until the next visit.

An album will not be created if any of the following criteria are met:

1. Images with captions
2. Unread divider - user sees some images, but not the rest
3. Date header - new day between deliveries

No, currently we have to use AWS EFS to share the media volume between the Coreapp and Webapp.

No, currently we do not support changing the default path to media storage (/usr/local/wamedia/). All media storage needs to be at this default location in order to work properly.

It is currently 7 days. If a cache has not been updated for longer than 7 days, it will pull the latest language pack from the server regardless of whether the element already exists in the pack or not.

Note: that the fallback language policy is deprecated beginning with v2.27.8 and the deterministic language policy is now the default policy.

If you create a translation in a new language you need to translate all the elements you use into that language. Otherwise, you might get "structure unavailable" errors since recipient's phone can't find an element it expects for the language it's in. These structure unavailable errors are seen when sending template messages using fallback policy.

If creating language translations is not an option for you at this moment, You can use deterministic policy to avoid these errors.

The WhatsApp Business API Client sends the Webhook callbacks to you via the Coreapp container. Therefore, your Webhook endpoint needs to be configured to accept inbound requests from the Coreapp.

If a Webhook fails to send a callback, the callback is put into a retry queue. Any callbacks sent after the initial callback failure will not be received. It is only after the initial failed callback succeeds that the rest will follow.

If a Webhook event isn't delivered for any reason (e.g., the client is offline) or if the Webhook request returns a HTTP status code other than 200, we will retry the webhook delivery. We will continue retrying delivery with increasing delays up to a certain timeout (typically 24 hours, though this may vary), or until the delivery succeeds.

Duplicates messages can be sent to a WhatsApp Webhook as the only guarantee provided is that messages will be received at least once (as opposed to exactly once). If this is affecting how messages are processed on your end, then we suggest dedup-ing Webhook messages based on the message ID.

Double-check your pass_through application setting. You won't receive any read status callbacks if you have enabled pass_through with WhatsApp Business API client v2.29.1 or higher.

If you'd like to receive the read status callback, disable the pass_through application setting. Note that by disabling pass_through, your database storage could grow quickly. See the Database Management documentation for more information on managing your database.

This is caused by a bug in an old version of the iOS client. We expect the errors to reduce overtime as the general population upgrades.

First check the callbacks for critical errors to diagnose the problem.

If you are seeing "Conflict: Detected multiple instances that share the same number", you need to check your containers. The most likely cause is you have multiple Docker containers trying to connect to the WhatsApp servers using the same WhatsApp account. Make sure you have only one container up and running. If you have old containers, shut them down and the error will go away.

If you want to test our more complicated high availability solution, see the High Availability documentation.

This is a known issue. Sometimes upgrading the WhatsApp Business API Client using the CloudFormation scripts also ends up requiring an update to the RDS DB stack. The new RDS stack won't have the same hostname as the original stack, and the Docker containers aren't able to connect to the database. The solution is to SSH into the EC2 instance created by CloudFormation and update the whatsapp.conf file with the new host name, then restart the Docker containers so they pick up the new settings.

This error occurs when the database has not been set up correctly.

• Make sure you are using either MySQL 5.7 or later or PostgreSQL 9.5.x, 9.6.x, 10.x.
• Your database password should not contain any of these characters: ?{}&~!()^.
• If you are using AWS, make sure your stack has a short name. See the Installation documentation for more information.

This happens if the Docker bridge is corrupted. The best remedy for this is to stop the Docker service and start it again. You can also try docker restart on your containers.

A "connection refused" error likely means the Coreapp is not running. Use docker ps to see if the Coreapp is up. If it is not up, take a look at the Docker logs. The Coreapp may be unable connect to the database. Make sure your database is set up correctly.

There are many reasons for this. Your Coreapp might be down or your database was not setup correctly. If these are not the case, please take a look at your Coreapp logs (or master Coreapp logs if you are running multiconnect). If you see database connection errors, it is likely your database is running out of connections. See the MySQL doc or PostgreSQL doc on this error.

We recommend bumping up the number of database connections on your database. 1000 database connections should be a safe number, but please make your own informed decision on number of connections. If the error persists, please open a support ticket.

If you are seeing this error but the missing mandatory parameter it refers to is set in your json body, it could be a json parsing error. This error can occur when the entire json payload is unparseable because of json formatting errors. Check the values of those parameters for invalid json characters, like a carriage return at the end. Sometimes parameters can be copied in with extra whitespace that might have characters that break json.

Structure unavailable errors occur when the phone cannot read the template message.

Templates are stored on the server. When a template message is sent using the messages node, only the namespace, language, element name, and localized parameters are sent to the phone but not the entire message. Once these values are delivered to the phone, it tries to render the message.

If any errors occur during rendering, a structure unavailable error is sent to the callback URL containing the recipient and message ID. These errors can happen due to a wrong namespace, localized parameter mismatch, wrong element name, etc.

Go to the WhatsApp Manager in your Facebook Business Manager to view the correct number of parameters. Double check that the namespace is correct and that the element name exists.

One common source of errors is not creating translations for all templates in use. For example, if you have 2 templates you generally send and you add a new language translation for one template, please make sure to add that new language translation for another template also. If you are planning to support more than one language, you need to provide translations for all templates in all supported languages.

The good news is that structure unavailable errors is usually due to mistakes in the messages API call and can be fixed by changing the send payload.

You need to first check if the contact exists before sending a message. See the Contacts documentation for more information on how to do this.

This error is due to Coreapp is not yet initialized. It means registration may not have gone through successfully. Please try registration before making a call to another end point. First step after installing WhatsApp Business API is login. Second step is registration. These two steps are necessary before making requests to any other end points.

All builds of the WhatsApp Business API Client have an expiry of 6 months from the date of release. If you see this error, upgrade to the latest released version as soon as possible.

WhatsApp runs experiments to measure and understand the impact of WhatsApp Business API notifications on user experience and the overall product in general. If the user you are messaging is in one of these experiments, they may not receive notifications from you even if they have opted in to receiving them.

If you are receiving an error similar to the following when setting up your AWS deployment, try changing to a stack name that uses 8 characters or less.

Country Name (2 letter code) [AU]:State or Province Name (full name) [Some-State]:Locality Name (eg, city) []:Organization Name (eg, company) [Internet Widgits Pty Ltd]:Organizational Unit Name (eg, section) []:Common Name (e.g. server FQDN or YOUR name) []:string is too long, it needs to be less than 64 bytes long Common Name (e.g. server FQDN or YOUR name) []:Email Address []:error, no objects specified in config file problems making Certificate Request Created device key for internal-wa-inc-name-LB-123456789.ap-southeast-1.elb.amazonaws.com

An empty profile object will be returned if the the Business Profile is only partially populated. Please upgrade to v2.21.4 to resolve this issue.

See the Business Profile Settings documentation for more information about completing your business profile.

Error code 471 relates to quality-based rate limits. See the Quality-Based Rate Limits documentation for more information.

The following are message template send side validation errors and why you may see them:

• "No message templates exist in language your-language" or "No message templates exist in language your-language and locale your-locale" — The given language pack does not exist. Check your Business Manager account.
• "Template your-template-name does not exist in language your-language" or "Template your-template-name does not exist in language your-language and locale your-locale" — You are trying to use a template that does not exist (has not been created or is not yet approved). If you attempt to send a message with a template that was deleted, you will also get this error.
• "Number of localizable_params num1 does not match the expected number of params num2" — You are trying to send a message template with parameters that do not match the number of parameters expected. Please check your API invocation for correctness.
• "your-template-name is a rich template and requires the template message API to be used" — You are trying to send a media message template as a regular message template. Make sure the message type is template. See the Media Message Templates documentation for more information.
• Once templates are approved in Business Manager (or deleted), it can take up to 20 minutes for the WhatsApp Business API client to receive the updated templates. If you are trying to send a message with a template that just got approved, and you get an error saying the template does not exist, you can retry sending the message after waiting the above specified time.

For WhatsApp Business API client's running v2.21.6, when the client is disconnected from the server it may remain disconnected for a few minutes (up to 4 minutes) and then will retry the connection. Upgrading to v2.23.4 will allow for less downtime for a client when attempting to connect to the server.

Prior to v2.29.x, it was possible for the outgoing message queue size to grow over time due to a bug. Upgrading to v2.29.3 resolves this issue.

The Coreapp will check the /usr/local/waent/data and /usr/local/waent/log directories within the Coreapp container, ensuring there is at least 10 MB of storage, otherwise it will give this critical error.

Check your logs and data directory to ensure you have enough space.

Currently, there is no way to do this. If you are not capable of handling inbound responses from your users over WhatsApp, we suggest sending an auto-reply message redirecting them to your proper support channels.

You should register a second phone number and spin up a second CloudFormation stack or Docker instance for testing. If you have two WhatsApp Business API Clients active using the same phone number, the server will kick you out because the encryption keys will conflict. We recommend having a second environment that you can use to test your non-production instance before you do any kind of migration on your production client.

Checking the Health is free and can be queried as often as necessary.

Read the Stats documentation to learn more about the application and database stats you can query. Application stats are stored in memory and are cheap to query. Database stats require more resources and should only be queried when needed.

Your business does not get notified when a customer changes their WhatsApp phone number. When you use the contacts node, the status for that number will be invalid.

If a customer's phone number becomes inactive, but the customer is still using WhatsApp, the customer will continue to have access to WhatsApp until/if the phone number is reassigned or reregistered.

WhatsApp strongly verifies whether a number provided actually belongs to a phone. The fact that a user has a WhatsApp account is proof that they confirmed the number and no one else has used that number to register on WhatsApp subsequently. However, it is not a guarantee of the physical location of the SIM card.

On the other hand, if a user's phone is lost or stolen, they can deactivate their WhatsApp account. To read more about how users can deactivate their account see the Lost and stolen phones FAQ.

No, there is no way to use the WhatsApp Business API to detect multiples devices using the same number.

A message payload from a user can be either a text or media file.

For text, there is not believed to be any identified danger.

For media files:

• Normally, it is expected that businesses have some protection software (i.e., anti-virus, anti-malware, etc.) in place to analyze any potential threats.
• WhatsApp is unable to identify or check the content of a file being transferred as it is end-to-end encrypted (the same also applies for text-only content).
• There is an option to prevent media files being automatically downloaded in the WhatsApp Business API Client. If the business does not want to receive any file from users, they can set the auto_download field to an empty array.

Please Contact Support with any information you have. We will investigate and shut down any fake numbers.

Starting with release v2.18.26, the App Stats endpoint allows for exporting internal metrics in the Prometheus text format. See the Instance Monitoring documentation for more information.

The WhatsApp Business On-Premises API Client requires a database to stores keys to decrypt messages sent between a business and customers. All messages on WhatsApp are encrypted with sender and receiver keys. Customer keys are stored on their mobile device and business keys are stored in the business' database. Learn more about WhatsApp's Security.

The WhatsApp Business Cloud API is an alternative wherein Meta hosts a business' database. The Cloud API allows you to implement WhatsApp Business APIs without the cost of hosting of your own servers. Learn more.