WhatsApp Business API

Programmable WhatsApp Business API from EnableX helps a business send and receive messages programmatically to/from users, can connect thousands of agents and bots to interact with customers. Additionally, the APIs can be integrated with numerous backend systems, such as CRM and marketing platforms.

Table of Contents

Overview

Communication between business and customer/users over WhatsApp Business Platform is carried out through messaging i.e. sending and receives messages. The WhatsApp Business API framework helps to effectively manage the processes around messaging through the following:

  • API: Its a Rest API Service with many API Collections/Routes used to initiate related transactions.
  • Webhook: It’s a Webhook over https to receive incoming messages, delivery notifications, status updates etc.

Basic understanding of the these covered in the following sections.

API Host URL

API Host: https://api.enablex.io/whatsapp/

Every major version release of UCaaS API will have a sub-directory named after the major version number. This is known as Base URL for a WhatsApp API Version, e.g.

Version Base URL: https://api.enablex.io/whatsapp/v1/

All WhatsApp Business API Collections are mapped to the Version base URL, e.g.

Templates Collection URL: https://api.enablex.io/whatsapp/v1/templates

API Authentication

WhatsApp Business API are always used for Server to Server Call. EnableX provides 2 different type of authentication mechanism for API Calls, they are:

  • HTTP Basic Authentication
  • Bearer Token

Either of these mechanism can be used to access WhatsApp Business API as per your application requirement.

HTTP Basic Authentication

The WhatsApp Business API uses HTTP Basic Authentication mechanism to authenticate API calls. Each API call is validated via the authentication header.

Each EnableX WhatsApp Project is assigned with Access Credentials in the form of APP ID and APP Key. These are to be used for HTTP Basic Authentication as explained below:

Authorization Header

  • APP ID: It is used as username.
  • APP KEY: It is used as password
  • Create base64 encoding for String APP ID:APP KEY. This encoded string is used in the Authorization header. Note that there is a colon (:) to separate APP ID and APP KEY in the string to encode

Sample API Call Example: Using HTTP Basic Authentication

POST https://api.enablex.io/whatsapp/v1/messages
Authorization: Basic XXXXXX   
Content-Type: application/json

In the above example:

  • The Authorization header contains a value XXXXX which is a base64 encoded string of the APP ID: APP KEY

Sample JSON for Error: Authentication failed.

{
  "message": "Authentication failed",
  "status": "Unauthorized",
  "reason": "invalid credentials or the account has been deactivated"
}

Bearer Token

WhatsApp API works on a Bearer Token with a validity of 60 minutes. Using the Token, any number of API call can be made before it expires.

Using the Token API, a token can be created or re-created if the previous one has expired. The Token API returns an Expiry Time too. This helps you to re-create another token before it expires. If API call is made using an expired token, error is returned.

Sample API Call Example: Using Bearer Token

GET https://api.enablex.io/whatsapp/v1/templates
Authorization: Bearer TTTTTTT
Content-Type: application/json

In the above example:

  • The Authorization header contains a value TTTTTTTTT which is a Token received from Token API.

Sample JSON for Error: Authentication failed.

{
  "message": "Authenticationnfailed",
  "status": "Unauthorized",
  "reason": "invalid credentials or the account has been deactivated"
}

API Responses

The WhatsApp API call  returns JSON Response. Different API Route returns success and error response differently. Given below examples:

Sample Success Response: On sending a message 

{
  "status": "processing",
  "message_id": "{message id}"
}

Sample Error Response: On repeated business initiated message to user without getting response from the user 

{
  "statuses": [
    {
      "id": "wamid.HBgMOTE4ODI2NzE5NjM1FQIAERgSNjQxNTQ1NEVCOEJEMUE0QjlEAA==",
      "status": "failed",
      "timestamp": "1683871427",
      "recipient_id": "918826719635",
      "errors": [
        {
          "code": 131047,
          "title": "Message failed to send because more than 24 hours have passed since the customer last replied to this number.",
          "href": "https://developers.facebook.com/docs/whatsapp/cloud-api/support/error-codes/"
        }
      ]
    }
  ],
  "business_phone": "918297867890"
}

Webhook Notification

A Webhook can be configured against each phone number you add to your project. The following type of notifications and messages will be posted to the Webhook using Raw JSON Body.

  • Incoming Messages: Whenever there is a incoming message sent by any user/customer, you get it posted.
  • Delivery Notification: Whenever there is a status updates on the message sent to any user/customer, viz. sent, failed, read etc., you get notified.
  • Template Updates: Whenever a new template submission gets approved or rejected; or if an approved template gets paused or disabled on spam complaints, you get notified.
  • Action/Reactions: Whenever user reacts with Emojis on a message sent, or acts on it (e.g. deletes a message); you get notified.

Important Points

  • Webhook URL must be hosted on https.
  • Any notification or message posting to Webhook URL must be acknowledged by returning HTTP 200 header in the same connection.

Sample Code: In PHP, to return HTTP 200 header.

<?php
header("HTTP/1.1 200 OK");
?>