Get Started

This tutorial describes how to set up the On-Premises API client, register a business phone number, update your settings, and send a test message.

The process of getting started with the API can be divided into 3 parts:

1. Prepare assets — Before you start, you must set up the assets required to complete the API integration, including a WhatsApp Business Account.
2. Install the On-Premises API Client — Install the API client. Once the client is working, you can update your application settings.
3. Start using the client — Register your phone number with an API call to /account and send a test message with a call to /messages.

Before You Start

Recommended Versions of Software

Step 1: Install the On-Premises API Client

Environment

At its core, the On-Premises API client is based on Docker. See Client Architecture for information on each component.

Equipment

The On-Premises API client will run on any internet-connected machine that can run Docker for Linux, either in a virtual machine, or on Linux server. For more information see the FAQ. 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).

Installation

There are two ways to get started with the On-Premises API:

• On-Premises installation — You can set up the Docker containers on your own using the Installation guide. We recommend beginning with one of the Developer Setups to get familiar with the setup process and sending messages. This On-Premises solution can be used on your computer before migrating to a production environment.
• Amazon Web Services (AWS): If you use AWS or would like a more standalone solution, see the AWS guide. The AWS solution sets up a whole On-Premises API solution with backups, recovery, and more in an AWS cloud you manage and own.

Update Your Settings

You can make changes to the Application Settings once the On-Premises API client is working. However, you don't get access to your On-Premises API client's different profile settings until registration is complete.

• The Application Settings pertain to how the client works — callback settings, Webhooks, on-call pager, sent status, media download behavior, etc. Note: It is strongly recommended you set up a Webhook URL in order to receive notifications about incoming messages or errors.
• The Business Profile Settings and Profile Settings cover your business's information such as address, email, website, industry, about information, and profile photo.

Step 2: Start Using the Client

Registration

Once you have the On-Premises API client up and running, you can register your phone number by sending an API call to the account endpoint.

Send A Test Message

You can send test messages using the messages endpoint. First, check the status of the phone number you are using for testing. You will need to send your WhatsApp account a message from the test phone number to enable 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 test phone number. If the message arrives it means that the installation has been successful. If it doesn't arrive, check your Webhook for notifications that may indicate any problems.

Security

See our Security guide for information on passwords, authentication, SSL configuration, network segregation, encrypted communications, HTTP headers, and the web server TLS protocol as related to the On-Premises API client.

Startup Process

The WhatsApp On-Premises API undergoes a startup procedure upon establishing a connection with the server. This process is essential to ensure a seamless and reliable means of sending and receiving messages. During this startup phase, the core application (coreapp) awaits the fulfillment of several prerequisites, including:

• Loading Template Messages: The API loads template messages from the server as part of its initialization process.

• Receiving and Processing Offline Messages: It also handles the reception and processing of offline messages.

If attempts to send messages are made while these prerequisites are not met, the core application will respond with a "Coreapp not ready" error message, and the logs will display a "Service not ready" error. It's important to note that this startup process is executed every time a new connection is established with the WhatsApp server. Consequently, if the core application is restarted or experiences a disconnection, the startup process will be initiated again to set the coreapp's state to "ready." This ensures the reliability and readiness of the WhatsApp On-Premises API for message communication.

Offline Message Processing

When there are no offline messages to be found, the offline message processing step is omitted. In other words, if there are no messages waiting in an offline state, this particular phase of message handling is bypassed.

Under typical conditions, the WhatsApp On-Premises API follows a standard protocol for handling offline messages. It awaits the reception and processing of all offline messages, with a predefined maximum timeout of 6 minutes. Once this 6-minute duration has elapsed, the offline message processing phase is considered as successfully completed.

Additional Suggestions

If we detect that you have violated any of our guidelines or policies, we reserve the right to limit or remove your access to WhatsApp.

Learn More

• Advanced Setup
• Postman Collection
• WhatsApp Business Platform
• WhatsApp Business Platform Changelog