WhatsApp Business API

Using the WhatsApp Business API

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

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