WhatsApp Business API Reference

WhatsApp is a fast, secure, and reliable way for businesses to reach their customers all over the world. This guide describes how businesses can use the WhatsApp Business API to interact with their customers.

This version of the WhatsApp Business API uses a REST API Architecture with JSON data formats. The API follows the standard HTTP request-response exchange.

This document covers:

WhatsApp Business API Root Nodes

NodeDescription

Contacts

Verify customer phone numbers to generate WhatsApp IDs

Groups

Create and manage groups

Health

Check the status of your WhatsApp application

Media

Upload, delete, and retrieve media

Messages

Send text, media, Message Templates, and group messages

Metrics

Collect Webapp metrics

Account

Register your WhatsApp account

Settings

Set WhatsApp application settings

Stats

Collect Coreapp and database stats

Support

Get help using the WhatsApp Business API

Users

Log in to get your authentication token and manage users

WhatsApp Business API Requests

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

POST /v1/contacts
{
    "blocking": "wait",
    "contacts": [    
        "6315551000",
        "6315551002",
        "631-555-1005"
    ]
}

A valid HTTP request includes the following components:

  • URL — The URL of the server along with the API endpoint for the request
  • Method — The action being requested of the endpoint
    Commonly used methods are POST, GET, DELETE, PATCH and PUT.
  • 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

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

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. You can run the command docker ps 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/loginendpoint. 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 as -d @filepath` to cURL.

WhatsApp Business API Responses

A WhatsApp Business API response has the following components:

  • HTTP Status Code — Status codes are issued by a server in response to a request made to the server. See HTTP Status Codes for more information.
  • Meta — Contains generic information such as WhatsApp Business API Client version.
  • Payload — Only returned with a successful response. The payload object name and contents vary based on the request. In the above examples, the payload is contacts because we sent a request to the contacts endpoint.
  • 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.

Note: Normally in a successful response, errors would not be present; they are included here purely for 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"
   }]
}