Getting Started

This document covers:

• Business Steps — Explains the (mostly) non-technical steps to take while setting up the WhatsApp Business API Client.
• Technical Steps — Explains the more technical side of the WhatsApp Business API set up such as installation, callbacks, and messages.
• Additional Suggestions

Start with the Business Steps to get your account set up properly, then follow the Technical Steps for installation of the WhatsApp Business API client.

Business Steps

1. Set up your WhatsApp Account in the Facebook Business Manager

For more detailed information on how to do this, please see Create a WhatsApp Account.

2. Add a phone number to your WhatsApp Account

Every WhatsApp account is a phone number. The phone number that you intend to use with WhatsApp must be clean, that is, with no previous registration or affiliation with WhatsApp. There are 3 types of eligible phone numbers for this product:

• Landlines - Probably the easiest to use as long as the developer can pick-up a phone call when doing the setup.
• Cellphones - Can be used as long as the number has not been used for WhatsApp in the last 6 months.
• 1-800 or toll-free numbers - Possible as long as the phone number is capable of receiving SMS or voice calls directly. You will not be able to use numbers that are behind IVR. (If you have a phone number already registered using a manual code before, it will continue to work normally.)

For more detailed information on picking and registering a phone number, see the Phone Number guide.

3. Add a display name to your WhatsApp Account

You must also define the display name for your selected number will have on WhatsApp.

The display name can be a maximum of 256 characters and should not contain emoji or any variation of the word "WhatsApp".

For more information on setting up a display name, see the Display Name guide.

You are now ready to deploy the WhatsApp Business API client using the Technical Steps below.

Technical Steps

1. Set up your environment

At its core, the WhatsApp Business API Client is based on Docker. Requirements depend on your load and situation. The WhatsApp Business API Client will run on any internet-connected machine that runs Docker. For instance, simple testing can be done on a laptop.

For a production environment server, 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.

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

There are two ways to get started with the WhatsApp Business API. You have two options:

• On-premise: You can set up the Docker containers on your own using our installation guide. This on-premise type solution can be used on your computer before porting to your production environment.
• Amazon Web Services (AWS): If you use AWS or would like a more standalone solution, please see our AWS guide. The AWS solution sets up a whole WhatsApp Business API solution with backups, recovery, and more in an AWS cloud you manage and own.

On-premise SetupAWS Setup

2. Register your WhatsApp Business API Client

With the client up, follow the registration steps. We recommend using our Postman collection to set a password and acquire the authentication token.

See steps for RegistrationLearn about Postman Collection

3. Test your installation

After your setup is complete, it is time to test your installation. First, check the contact of your personal WhatsApp phone number.

Checking Contacts

Before you can send your first test message with the WhatsApp Business API, you will need to send your WhatsApp Account a message by adding it to your personal phone's address book. This enables the Customer Service window, which allows you to send any type of message within the 24-hours window (See Cut-off Control for details).

Then, send a text message to your personal WhatsApp number. If the message arrives it means that the installation has been succesful.

Sending Text Messages

Optionally, you can download the WADebug tool to ensure that your Business API client is set up properly.

4. Set your settings

Control different settings of your WhatsApp Account including the Business Profile, profile picture, about, and much more.

Manage Settings

5. Create a backup

Now that you have a working WhatsApp Business API client and have set the settings, create a backup. This allows you to restore everything you have just done on another machine without having to go through registration again. Make sure to keep your password in a secure place.

Creating a Backup

6. Set up Webhooks

You can also set up Webhooks so you can process incoming messages from people who respond to you on WhatsApp. These Webhooks process incoming text, location, media such as pictures and documents, and the status of the messages you've sent. We've prepared a code sample so that you can test this with a couple of clicks.

If the Webhook URL is not set, then callbacks will be dropped. Callbacks are an important channel to deliver, both timely notifications as well as out-of-band errors, and it is thus highly recommended to configure the Webhook URL endpoint.

Setting up WebhooksProcessing WebhooksWebhooks Test App

7. Send media

Sending and receiving text messages is just the beginning! You can also send images and other media files.

Sending Media

8. Start sending message templates

You can set up message templates that are standard messages you may want to send to your customers. The benefits of message templates versus plain text messages are many and will continue to grow. To highlight just one, when sending a message to a contact for the first time, WhatsApp displays buttons to mark the conversation as spam or block the number. With message templates, we know already that the template is a valid one, so these buttons won't show if your business is verified, allowing for a better user experience.

Sending Message Templates

9. Continue building and integrating with your systems!

Additional Suggestions

DO Check the FAQ before opening a Direct Support ticket. They are always being updated. Ask questions on Developer Support in English. We are a global team. Use multiple phone numbers for development, testing and production. Provide product feedback. Direct Support is the best channel for that. Provide details to reproduce your issue. Logs, Support info from the health and support nodes, API calls to reproduce, etc.

DON'T Use 1-800 numbers for testing. Create a Business Manager only for WhatsApp integrations. Use an existing one if available.