WhatsApp FAQ

Getting Started

In order to ensure a high quality experience for businesses and users, we're in a limited public preview. If you'd like to work with us, submit more information about your business for consideration as we continue to expand our availability, or reach out to your Facebook representative if you already have one.

Yes, end-to-end encryption of the message happens between the WhatsApp Business API Client and the end user. 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).

No. The WhatsApp Business API solution requires a clean number.

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.

Toll-free numbers are allowed as long as your country code is included. The reason is that toll-free numbers without country codes cannot be uniquely identified — the same number can apply for two different countries.

Also note that there are added complexities around toll-free numbers. Typically, if you call a toll-free number with the country code when you're inside the country, it will fail. This means that there is a chance your customers from your country will try to dial what shows in the business contact (country code included) and they won't be able to reach you. If this is a concern, you will need to let them know explicitly.

WhatsApp and its users value end-to-end encryption. All messages on WhatsApp are encrypted with high levels of encryption. Every message is encrypted with sender and receiver keys which are ratcheted forward each time a message is sent. WhatsApp cannot read these messages because it does not have keys to decrypt the messages. The keys are stored by user in their mobile device and by the business in the database. This is why the WhatsApp Business API Client is a hosted solution that requires a database. Having an API to send messages on will break end-to-end encryption which is against the WhatsApp philosophy.

See WhatsApp's Security for more information and to access the WhatsApp Encryption Overview white paper.

Installation

Yes! by default, the WhatsApp Business API Client attempts to communicate using chatd over port 5222. For best experience, open port 5222 for all outbound traffic. This does not pose a security issue since the traffic is only outbound from your data center.

If you cannot open port 5222, the WhatsApp Business API Client attempts to use port 443. If your firewall or proxy is still terminating connections, please reach out to the WhatsApp team by submitting a question through Direct Support to debug.

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

MySQL 5.7 or above is required for WhatsApp Business API Client storage. 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.

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

Whitelisting can be done by hostname rather than IP Address. See the Hostnames section of the Debugging Your Network 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 Debugging documentation for more information.

Data Storage

Only MYSQL is supported. If you run Docker by yourself, you must provide a MYSQL database for the containers to connect to. Using the AWS template sets up a MYSQL database by default.

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

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

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

The script works with both webapp and coreapp containers.

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 MySQL 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 local storage (instead of in the MySQL 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.

You need archive or delete the existing logs files or implement any maintenance procedure as per your business requirements. We have not implemented a solution in the WhatsApp Business API Client to rotate the logs; we expect you will take care of the operational maintenance.

A part the logs files, you also have to ensure the media shared folder is regularly archived or cleaned up (use docker inspect your- container-id to check where the folder is), as all the media files you are sending or receiving are stored there.

Also, if the pass_through is set to false in the application settings, then all messages are saved in local storage until they are explicitly deleted.

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.

Registration

Yes, we can set up a new phone number or change the verified name when you are ready to go live.

You can register new phones numbers and delete old one in your WhatsApp Account in the Facebook Business Manager.

  1. In your WhatsApp Account, go to Settings.
  2. Click on WhatsApp Manager.
  3. Select the Phone Numbers tab. This is where you can manage all the phone numbers for this account.

Unfortunately, you will need to pick a different phone number that is capable of receiving SMS or voice in order for us to send the registration code. In the past, we had allowed manual registration codes, but this is no longer supported. Phone numbers that used manual registration codes before will continue to be supported as required. For any new phone numbers, we will only deliver registration codes via SMS or voice call.

If registration is failing with "sms" because of too many attempts and you see an "access denied" message, then please try registering with "voice"

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.

Authentication

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.

Sending Messages

See Understanding How to Get Opt-in for WhatsApp for more information on presenting your users with an opt-in option.

In the current stable release (2.19.x) the following types are supported: text, message templates, images, documents and audio.

No.

If a user contacts an enterprise, the enterprise can respond with any type of message in the next 24 hours. This type of message is free.

But if the enterprise is contacting a user before the user sends a message or after more than 24 hours have passed, the enterprise can only send a message template. This is a paid notification.

Free-form text messages and media messages will not work outside this 24 hour window. They will result in a failure callback with error 470.

The maximum tested outbound message rate is 20 messages per second.

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 or being inactive for a period of time.

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.

Yes! WhatsApp allows you to format selected text inside your messages with Bold, Italics, Strikethrough or Monospace.

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. Please refer to the Creating Message Templates documentation for the information we will need from you to process your Message Template creation.

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.

There may be cases where you need more time to handle a customer query and may only be able to provide a response after 24 hours. We recommend creating message templates to either:

  • deliver the result to the user, or
  • prompt the user to reply in order to activate the customer service window.

In both cases, please ensure you provide as much context to the message template as possible. For example:

  • "Hello {{1}}, regarding the issue you reported earlier, we regret to inform you that {{2}}. Apologies for any inconvenience caused."
  • We have updates regarding your ticket. Please respond back if you'd like to continue support."

Media

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 data volumes, such as the incoming 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/

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's up to you when to delete media.

Even if the recipient has read the message, it does not mean that it downloaded media successfully. There are no callbacks for successful media download.

If media is time sensitive, it is best to remove it from the media volume when the time is up. It will be stored on WhatsApp servers for 7 days after which it will be removed.

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.

Message Templates

Reasons a Message Template might be rejected include:

  • Contains potentially abusive content such as abusive language or spam-like content
  • Contains promotional content
  • Does not match the select tag type
  • Formatted incorrectly

Yes, Message Templates support all WhatsApp messaging characters and formatting including emojis, bolding, italics, etc. For emojis, you will need to use the emoji character (copy/paste) rather than its unicode equivalent.

The device will first load from cache, and if an element exists, it will unpack the message using that Message Template. So instead of modifying Message Templates, it's safest to simply add a new one with a different element name. That will guarantee that the language pack gets re-downloaded when it can't find that element. Storage costs of Message Templates are negligible so there's no absolute need to delete Message Templates.

See Sending Message Templates — Language for more information.

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.

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.

Using media in Message Templstes is not currently supported, but is in development.

There is no maximum limit. You may create as many Message Templates as you need.

There is no limit to the number of parameters allowed in a Message Templates.

Webhooks

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.

Errors

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 MySQL 5.7 or later.
  • Your MySQL password should not contain any of these characters: ?{}&~!()^.
  • If you are using AWS, make sure your stack has a short name. See the Installation and Upgrading 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 MySQL database. Make sure your MySQL database is set up correctly.

There are many reasons for this. Your Coreapp might be down or your MySQL 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 on this error.

We recommend bumping up the number of database connections on your MySQL 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 phone cannot read the the template message. Message templates are stored on server side. When a template message is sent using Message API, only localized parameters, namespace, language, and element_name are sent to the phone but not the entire message. Once these values delivered to the phone, it tries render to form a message. For any errors during rendering then a structure unavailable error is send to callback and oncall pager. These errors can be a wrong namespace, localized parameter mismatch, wrong element_name etc. You may navigate to "WhatsApp Manager" in your "Facebook Business Manager" account to view correct number of parameters.

The error itself gives valuable information. In the callback it will have the recipient and message ID and in the oncall pager group it will have the element name and recipient phone number.

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.

Advanced users may choose to use "deterministic" mode to avoid these requirements but please watch your errors closely.

The good news is that the vast majority of the time a "structure unavailable" failures are due to incorrect use of Send Messaging API 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.

Other

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.

For audio/video call functionality, we are exploring how we can enable a better experience for the user when a business cannot support this.

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.