Overview

This document shows you how to make WhatsApp Business API requests and what the returned responses might look like.

Authentication

To use the WhatsApp Business API, you must authenticate yourself. Only users with valid authentication tokens can access the service.

Authentication Flow

Tokens

For your initial login, use your username and password for basic authentication. For all other secure interactions, you must use the bearer token that is returned after a successful login.

The tokens are sent in the authorization header of the HTTP request for many of the WhatsApp Business API calls. In particular, notice in the following example that the type of authorization that is used with this token is Bearer.

HTTP-METHOD /secured-path
Authorization: Bearer your-auth-token

For all secured paths, we validate the token. During validation, if a token is found to be expired, that token is removed from the system. Upon successful validation, the request is allowed to proceed. Requests made with an invalid token receive a 401 Unauthorized error code.

Expiration

You can use your token for authentication until the token expires. A token can expire for these reasons:

• Periodic - Token are set to expire after a default time, such as 7 days. The expires_after parameter in the response provides the expiration date for the token. Log in again to generate a new token.
• Explicit - Tokens are revoked when you log out, which is one way to explicitly revoke the token. If an user is removed from the system, then all associated tokens with that user are deleted.

Headers

Many client software apps (e.g., Postman) take the username:password parameter and build the authentication header automatically. If you need to build it yourself, here are the basic steps:

1. Create the username:password string.
2. Use your favorite tool to base64-encode the string.

The base64 encoding for the default username and password string admin:secret results in YWRtaW46c2VjcmV0, so the admin credentials will be Authorization: Basic YWRtaW46c2VjcmV0.

API Keys

services:
...
  waweb:
  ...
    environment:
    ...
    WA_API_KEY: your-api-key-token

WhatsApp Business API Requests

You can use the WhatsApp-provided Postman Collection or cURL API calls to send requests.

A valid HTTP request includes the following components:

• Method — The action being requested of the endpoint
  Commonly used methods are POST, GET, DELETE, PATCH and PUT.
• URL — The URL of the server along with the API endpoint for the request
• Headers — Meta information about the request
  All requests that contain a message body should set the Content-Type in the header (e.g.,“Content-Type: application/json”). This uses UTF-8 character encoding, and charset=utf-8 is the default for application/json.
  Headers must also contain appropriate authentication information; see the Login and Authentication documentation for more information.
• Body: Contains the payload data, if any

Example

This cURL API request example of the WhatsApp Business API format uses the contacts node:

curl -X POST \
  https://your-webapp-hostname:your-webapp-port/v1/contacts \
  -H 'Authorization: Bearer your-auth-token' \
  -H 'Content-Type: application/json' \
  -d '{
  	"blocking": "wait",
  	"contacts": [ "6315551000", "6315551002", "631-555-1005" ]
  }'

• your-webapp-hostname is the hostname, FQDN or IP address, where the Webapp container or the load balancer runs.
• your-webapp-port is optional and required only if either the load balancer listens on or if the Webapp container is mapped to a non-standard HTTPS port. Note: If using Docker to run your WhatsApp Business API client, you can run the docker ps command to find the port.
• /v1/contacts is the endpoint to send the data request to
• your-auth-token is obtained after you log in using the /v1/users/login endpoint. See the Login and Authentication documentation for more information.
• A request body is included in the above example. Alternatively, the contents of body can be stored in a file and passed with -d @filepath`.

WhatsApp Business API Responses

A WhatsApp Business API response has the following components:

• HTTP Status Code — Status codes are issued by the server in response to a request made to the server. See HTTP Status Codes for more information.
• Payload — Only returned with a successful response. The payload object name and contents vary based on the request.
• Meta — Contains generic information such as the WhatsApp Business API client version.
• Errors — Only returned with a failed request. Contains an array of error objects that are present when there is an error. See the Error Codes for more information.

Example

In this example, the payload is contacts because we sent a request to the contacts endpoint in the above request example.

Note: Normally in a successful response, errors would not be present; they are included here purely as an example.

200 OK
  
{
   "contacts": [
      {
         "input": "1-631-555-1002",
         "status": "valid",
         "wa_id": "16315551002"
      },
      {
         "input": "6315551003",
         "status": "valid",
         "wa_id": "16315551003"

      }
   ],
    
   "meta": {
        "version": "whatsapp-business-api-client-version",
        "api_status": "deprecated" | "experimental" | "stable"
   }

   "errors": [{
       "code": error-code,    
       "title": "error-code-title",
       "details": "optional-detailed-error-message"
   }]
}

Learn More

• Client Architecture
• Security
• Advanced Topics such as webhooks, two-factor authentication, monitoring, and more.

Capacity Rate Limits

Capacity rate limiting is imposed on each available API endpoint and will return the appropriate HTTPS error codes (e.g., 429, 503, etc.) depending on the state of the system.

Two forms of capacity rate limiting are currently supported:

• Request rate limiting — Request rate limiting is the throttling of incoming requests on an API endpoint. When the number of requests per second limit is reached, the endpoint will start returning a 429 error code.
  
  • Beginning with v2.25.3, the request rate limit for the messages endpoint is 50 requests per second with bursts allowed up to 150 requests per second.
  • For versions prior to v2.25.3 and all other endpoints, the request rate limit is 20 requests per second with bursts allowed up to 60 requests per second.
• Concurrent rate limiting — Concurrent rate limiting is the throttling of incoming requests when the Coreapp itself is under heavy load (e.g., job queue size grew too large). At this point, the endpoint will start returning a 503 error.

When you hit either of these capacity rate limiting scenarios, you should halt any further requests and slow the pace of your API requests. If you start seeing many capacity rate limit errors, it would be advisable to build a queue on your end to throttle the requests.

Next Steps

• Get Started with the On-Premises API.