WhatsApp Business API – Messaging

This API Collection is meant to send outgoing messages from Business. It covers Business Initiated Message sending using Pre-Approves Templates and sending Session Messages with different type of contents.

Table of Contents

• Overview
• Send Message using Pre-Approved Templates
  • Send Text Message
  • Send Rich Media Contents
  • Send Quick-Reply Buttons
  • Send Call-to-Action Buttons
• Send Message without Template
  • Send Text Message
  • Send Rich Media Contents
  • Send Location
  • Send Interactive Buttons
  • Send Interactive List
  • Send Contact
• Mark incoming Message as “Read”
• Responses & Notifications
  • API Responses
  • Webhook Notifications

Overview

This API Collection is related to sending out messages to customer or users. These are called outgoing messages from business point of view.

Using a single API Route, you can send messages with different kind of contents with or without a template. The JSON Payload is different for different type of contents. Therefore, the following sections explains about how to prepare the JSON Payload to cover different type of messaging.

Send Message using Pre-Approved Templates

Following section explains how to send a message using a pre-approved template. The API Call may take dynamic content or data to be replace related placeholders in the template. 

Please note that when business sends a message to start a Business-originated Conversation, it is necessary to use a pre-approved template. However, in all other contexts whether responding to a user-initiated message or sending follow-up messages within 24 hours, there are no restrictions on the use of pre-approved templates. Follow-up messages are also known as Session Messages. Business may opt to send Session messages with or without Template.

• API Route: https://api.enablex.io/whatsapp/v1/messages
• Request: POST
• Authorization: Bearer Token / Basic

Send Message with Text-Template

JSON Payload Example: Refer the following JSON Payload to send message using a Template with Text Content that doesn’t have any data placeholder.

{
  "to": "{mobile number}",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "{lang_code}"
    },
    "name": "{template name}"
  }
}

JSON Payload Example: Refer the following JSON Payload to send message using a Template with Text Content. If the body of the template definition had placeholder variable, you must provide data for all Placeholder Variables.

{
  "to": "{mobile number}",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "{lang_code}"
    },
    "name": "{template name}",
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "{placeholder data}"
          }
        ]
      }
    ]
  }
}

Common data in Payload Explanation: This is to explain all common keys and objects used in payload to send message of different kind using pre-approved template.

Key/Object	Data Type	Constraint	Description
to	String	Required	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Required	Use template
template	Object	Required	Object contains Template Information and placeholder data for different components

Template Object Explanation

Key/Object	Data Type	Constraint	Description
language	Object	Required	Language infomration
language.policy	String	Optional	Use deterministic
language.code	String	Required	Use language code using which the Template was created
name	String	Required	Template name
components	Array	Optional	This is used to define run-time data for placeholder variables and interactive buttons etc. for different type components.

Body Component in Payload Explanation: Body Component is used only when the template is created with placeholder variables in body texts. If no placeholder variable is used, the Body Component will be used at all.

Key / Object	Data Type	Constraint	Description
type	String	Required	Use body
parameters	Array	Required	Each Object in the array to carry value for placeholder variables. Objects are to be placed in the same order as they represent related placeholder in the Template.
parameters[n].type	String	Required	Use text
parameters[n].text	String	Required	Value for the placeholder

Send Message with Rich Media Template

JSON Payload Example: Refer the following JSON Payload to send message using a Template defined with Rich Media Content, viz. image, video, document, audio. The given example shows component definition for image. Similarly, you can create component for video, document, audio.

{
  "to": "{mobile number}",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "{lang_code}"
    },
    "name": "{template name}",
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "{public media url]"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "{placeholder data}"
          }
        ]
      }
    ]
  }
}

JSON Explanation: Refer back previous sections for explanation of different parts of the JSON Payload.

• Common JSON Payload
• Template Object
• Body Component

Rich Media Component Explanation: Covers image, video, audio, document components.

Key / Object	Data Type	Constraint	Description
type	String	Required	Use header
parameters	Array	Required	Object in the array to carry definition of one type of Rich Media content only.
parameters[n].type	String	Required	Use one of the following enumerated content type in sync with your Template definition: image, video, audio, document
parameters[n].image	Object	Required	Use only when parameters[n].type is image
parameters[n].video	Object	Required	Use only when parameters[n].type is video
parameters[n].audio	Object	Required	Use only when parameters[n].type is audio
parameters[n].document	Object	Required	Use only when parameters[n].type is document

Image Object Explanation: Covers video, audio, document objects too.

Key	Data Type	Constraint	Description
link	String	Required	Publicly accessible https hosted URL for the media file
filename	String	Optional	File name with extension. Use it only with document
caption	String	Optional	Caption for the media file. Not used with audio.

To know how to use other media types and their specification, click here.

Send Message with Quick Reply Button Template

JSON Payload Example: Refer the following JSON Payload to send message using a Template defined with Quick Reply Buttons which don’t require place holder variables.

{
  "to": "{mobile number}",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "{lang_code}"
    },
    "name": "{template name}",
    "components": []
  }
}

Note: A Quick Reply Template may also have Header and Body texts with placeholder variables. In such cases, related components to be used to define related data.

Send Message with Call to Action Button Template

JSON Payload Example: Refer the following JSON Payload to send message using a Template defined with Call to Action Buttons .

{
  "to": "{mobile number}",
  "type": "template",
  "template": {
    "language": {
      "policy": "deterministic",
      "code": "{lang_code}"
    },
    "name": "{template name}",
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "{number}",
        "parameters": [
          {
            "type": "text",
            "text": "{placeholder data for url}"
          }
        ]
      }
    ]
  }
}

Note: A Call-to-Action Template may also have Header and Body texts with placeholder variables. In such cases, related components to be used to define related data.

Button Component Explanation:

Key / Object	Data Type	Constraint	Description
type	String	Required	Use button
sub_type	String	Required	Use url
index	String	Required	Order number of the button. Index number starts with 0 for the first button.
parameters	Array	Optional	It appears if any URL has placeholder variable. Object in the array to carry definition of placeholder data
parameters[n].type	String	Required	Use text
parameters[n].text	String	Required	Part of URL to be used as data for placeholder variable

Send Message without Template

Following section explains how to send a message without a pre-approve template.

Note that other than Business Initiated Conversation, business is not restricted to use pre-approved templates to send message. So when business responds to a user-initiated message or when business sends follow-up messages within 24 hours, any content may be used to send a message.

Once the conversation starts, business remains in a conversation session with the user for 24 hours. Therefore, all follow-up messages are called Session Messages. If business needs, a pre-approved template may also be used to send as a Session Message.

• API Route: https://api.enablex.io/whatsapp/v1/messages
• Request: POST
• Authorization: Bearer Token / Basic

Send Message with Text Content

JSON Payload Example: Refer the following JSON Payload to send text message.

{
  "to": "{mobile number}",
  "type": "text",
  "recipient_type": "individual",
  "text": {
    "body": "{body text content}"
  }
}

Payload Explanation

Key	Data Type	Constraint	Description
to	String	Required	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Required	Use text
recipient_type	String	Optional	Use individual
text	Object	Required	Object for text contents
text.body	String	Required	Body content for the message

Send Message with Rich Media Content

JSON Payload Example: Refer the following JSON Payload to send a message with a Rich Media file like image, audio, video, document and sticker. The examples given below shows how to send an image file. You need to use related type of payload to send other type of media.

{
  "to": "{mobile number}",
  "type": "image",
  "image": {
    "caption": "{caption}",
    "link": "{public image url}"
  }
}

Payload Explanation

Key	Data Type	Constraint	Description
to	String	Required	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Required	Enumerated values: image, video, audio, document, sticker. Use one
image	Object	Required	Only if type:image is used.
video	Object	Required	Only if type:video is used.
audio	Object	Required	Only if type:audio is used.
document	Object	Required	Only if type:document is used.
sticker	Object	Required	Only if type.sticker is used

Image Object Explanation: Covers video, audio, document objects too.

Key	Data Type	Constraint	Description
link	String	Required	Publicly accessible https hosted URL for the media file
filename	String	Optional	File name with extension. Use it only with document
caption	String	Optional	Caption for the media file. Not used with audio.

To know how all other media types are defined and their specification, click here.

Send Message with Location

JSON Payload Example: Refer the following JSON Payload to send a message with location information.

{
  "to": "{mobile number}",
  "type": "location",
  "location": {
    "longitude": "{longitude}",
    "latitude": "{latitude}",
    "name": "{location name}",
    "address": "{location address}"
  }
}

Payload Explanation

Key	Data Type	Constraint	Description
to	String	Required	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Required	Use location
location	Object	Required	Object contains location content
location.longitude	String	Required	Location’s Longitude
location.latitude	String	Required	Location’s Latitude
location.name	String	Optional	Name of the Location
location.address	String	Optional	Address of the Location

Send Message with Contact

JSON Payload Example: Refer the following JSON Payload to send a message with Contact information.

{
  "to": "{mobile number}",
  "type": "contacts",
  "contacts": {
            "addresses": [
              {
                "city": "{contact city}",
                "country": "{contact country}",
                "country_code": "{contact country code}",
                "state": "{contact state}",
                "street": "{contact street}",
                "type": "{home or work}",
                "zip": "{contact zip}"
              }
            ],
            "birthday": "{contact birthday}",
            "emails": [
              {
                "email": "{contact email}",
                "type": "{work or home}"
              }
            ],
            "name": {
              "formatted_name": "{contact formatted name}",
              "first_name": "{contact first name}",
              "last_name": "{contact last name}",
              "middle_name": "{contact middle name}",
              "suffix": "{contact suffix}",
              "prefix": "{contact prefix}"
            },
            "org": {
              "company": "{contact org company}",
              "department": "{contact org department}",
              "title": "{contact org title}"
            },
            "phones": [
              {
                "phone": "{contact phone}",
                "wa_id": "{contact wa id}",
                "type": "{home or work}"
              }
            ],
            "urls": [
              {
                "url": "{contact url}",
                "type": "{home or work}"
              }
            ]
          }
        ]
      }
}

Payload Explanation

Contacts Object Explanation: Covers only key/objects related to Contacts Object.

Key / Object	Data Type	Description
to	String	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Use contacts
contacts	Object	This object appears with type:contact. It contains location information
contacts.addresses	Array	Array of objects. Each Object is Address
contacts.birthday	String	Date of Birth
contacts.emails	Array	Array of Objects. Each Object is an Email Address
contacts.name	Object	Name. It breaks down name into parts defined as keys
contacts.org	Object	Organization
contacts.phones	Array	Array of Objects. Each Objec is a Phone Number
contacts.urls	Object	URL of different type/category

Send Message with Interactive Buttons

JSON Payload Example: Refer the following JSON Payload to send a message with Interactive Button. This helps to create interactive, engaging contents. User can click one of the button to respond to.

{
  "to": "{mobile number}",
  "recipient_type": "individual",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "{body text}"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "{unique button id}",
            "title": "{button title}"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "{unique button id}",
            "title": "{button title}"
          }
        }
      ]
    }
  }
}

JSON Payload Example:

Key / Object	Data Type	Description
to	String	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Use interactive
interactive	Object	This object appears with type:interactive. It contains interactive button and content information
interactive.type	String	Use button
interacive.body	Object	Body Object
interactive.body.text	String	Text of the Body
interactive.action	Object	Object contains Quick Reply Buttons
interactive-action.buttons	Array	It contains one or more button defintions

Payload Explanation

Button Object Payload Explanation: Button Array is used only to define one or more buttons. Buttons appear in the message in the same order as they are defined. You may add an id and label to each button.

Key		Constraint	Description
type	String	Required	Use reply
reply	Object	Required	Define Quick Reply Button
reply.id	String	Required	Give an ID to your buttons. ID should be unique for each button. This ID is returned on clicking of the button. You are suggested to use increasing numbers to use as ID.
reply.title	String	Required	Label of the button.

Send Message with Interactive List

JSON Payload Example: Refer the following JSON Payload to send a message with Interactive List. This list is presented to user as list of categorized options to choose. User can click one of the button to respond to. This helps to create interactive, engaging contents.

{
  "to": "{mobile number}",
  "recipient_type": "individual",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "{header text}"
    },
    "body": {
      "text": "{body text}"
    },
    "footer": {
      "text": "{footer text}"
    },
    "action": {
      "button": "{action button text}",
      "sections": [
        {
          "title": "{section title}",
          "rows": [
            {
              "id": "{unique id for list item}",
              "title": "{list item title}",
              "description": "{list item description}"
            }
          ]
        },
        {
          "title": "{section title}",
          "rows": [
            {
              "id": "{unique id for list item}",
              "title": "{list item title}",
              "description": "{list item description}"
            },
            {
              "id": "{unique id for list item}",
              "title": "{list item title}",
              "description": "{list item description}"
            }
          ]
        }
      ]
    }
  }
}

Payload Explanation

Key / Object	Data Type	Description
to	String	Recipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
type	String	Use interactive
interactive	Object	This object appears with type:interactive. It contains interactive button and content information
interactive.type	String	Use list
interactive.header	Object	Header Object
interacive.body	Object	Body Object
interacive.footer	Object	Footer Object
interactive.action	Object	Object contains List Items
interactive.action.button	String	Label for the Action Button to open the List
interactive.action.sections	Array	Array of Objects. Each Object defines a Section (Category) and each List Item under it.

Section Object Payload Explanation: It defines one section object. A Section can be treated as a catalog or category where each section may have one or more listed items for the user the choose from. Sections appear in the message in the same order as they are defined. You may add an id, title and description against each listed item.

Key/Object	Data Type	Constraint	Description
title	String	Required	Section Title. This helps to categorize your listed items
rows	Array	Required	It defines each listed item in the section in form of an object
rows[n].id	String	Required	Give an ID to your listed item. ID should be unique for each item. This ID is returned on clicking of the item. You are suggested to use increasing numbers to use as ID.
rows[n].title	String	Required	Title for the listed item
rows[n].description	String	Optional	Description for the listed item

Mark Incoming Message as “Read”

Any incoming message for business can be marked as “Read”. Note that when a message is marked as “Read”, the sender’s phone shows the message with double Blue Tick.

• API Route: https://api.enablex.io/whatsapp/v1/messages/read
• Request: POST
• Authorization: Bearer Token / Basic

JSON Payload example:

{
  "messageId": "{message id}"
}

Response JSON:

{
  "success": true
}

Responses & Notifications

API Responses

Success Response JSON: When a message is sent usign API, WhatsApp accepts for processing. Each API Post to send a message is assigned with a message_id. Subsequently all delivery status updates are posted against this message_id.

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

Webhook Notifications

Delivery Status Updates JSON: An Outgoing Message changes it’s status in its life time as it passes through different stages until its read and/or deleted by the user. All updates on Deliver Status are notified on Webhook in the following format:

{
  "statuses": [
    {
      "id": "{message id}",
      "recipient_id": "{recipient phone}",
      "status": "{status code}",
      "timestamp": "{unix timestamp in utc}",
      "type": "message",
      "conversation": {
        "id": "{conversation id}",
	"expiration_timestamp":"{unix timestamp in utc}",
        "origin": {
          "type": "user_initiated/business_initiated"
        }
      } 
    }
  ],
  "business_phone": "{brand phone}"
}

Example for a failed Status Notification: You are barred from sending 2nd business-initiated message using templates within 24 hours of the 1st message which was not replied by the recipient of the message. In such case the following notification will be received.

{
  "statuses": [
    {
      "id": "{message id}",
      "recipient_id": "{recipient phone}",
      "status": "failed",
      "timestamp": "{unix timestamp}",
      "type": "message",
      "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": "{business phone}"
}

List of Delivery Status

Status	Description
sent	A message sent by business is in transit
failed	A message sent by business failed in processing or failed to deliver. A reason for the failure will be included in Webhook notification.
warning	A message sent by business contains an item in a catalog that does not exist.
delivered	A message sent by business is delivered to the recipient’s device.
read	A message sent by business is read by the user. Read notifications are only available from users who have read receipts enabled.
deleted	A message sent by business is deleted by the user.