WhatsApp Business API for 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.

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# 1: 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# 2: 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 / ObjectData TypeConstraintDescription
toStringRequiredRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typeStringRequiredUse template
templateObjectRequiredObject contains Template Information and placeholder data for different components

Template Object Explanation

Key / ObjectData TypeConstraintDescription
languageObjectRequiredLanguage infomration
language.policyStringOptionalUse deterministic
language.codeStringRequiredUse language code using which the Template was created
nameStringRequiredTemplate name
componentsArrayOptionalThis 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 / ObjectData TypeConstraintDescription
typeStringRequiredUse body
parametersArrayRequiredEach 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].typeStringRequiredUse text
parameters[n].textStringRequiredValue 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 / ObjectData TypeConstraintDescription
typeStringRequiredUse header
parametersArrayRequiredObject in the array to carry definition of one type of Rich Media content only.
parameters[n].typeStringRequiredUse one of the following enumerated content type in sync with your Template definition: image, video, audio, document
parameters[n].imageObjectRequiredUse only when parameters[n].type is image
parameters[n].videoObjectRequiredUse only when parameters[n].type is video
parameters[n].audioObjectRequiredUse only when parameters[n].type is audio
parameters[n].documentObjectRequiredUse only when parameters[n].type is document

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

KeyData TypeConstraintDescription
linkStringRequiredPublicly accessible https hosted URL for the media file
filenameStringOptionalFile name with extension. Use it only with document
captionStringOptionalCaption for the media file. Not used with audio.

To know how to use other Rich 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 / ObjectData TypeConstraintDescription
typeStringRequiredUse button
sub_typeStringRequiredUse url
index StringRequiredOrder number of the button. Index number starts with 0 for the first button.
parametersArrayOptionalIt appears if any URL has placeholder variable. Object in the array to carry definition of placeholder data
parameters[n].typeStringRequiredUse text
parameters[n].textStringRequiredPart 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

KeyData TypeConstraintDescription
toStringRequiredRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typeStringRequiredUse text
recipient_typeStringOptionalUse individual
textObjectRequiredObject for text contents
text.bodyStringRequiredBody 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

KeyData TypeConstraintDescription
toStringRequiredRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typeStringRequiredEnumerated values: image, video, audio, document, sticker. Use one
imageObjectRequiredOnly if type:image is used.
videoObjectRequiredOnly if type:video is used.
audioObjectRequiredOnly if type:audio is used.
documentObjectRequiredOnly if type:document is used.
stickerObjectRequiredOnly if type.sticker is used.

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

KeyData TypeConstraintDescription
linkStringRequiredPublicly accessible https hosted URL for the media file
filenameStringOptionalFile name with extension. Use it only with document
captionStringOptionalCaption for the media file. Not used with audio.

To know how all other rich 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

KeyData TypeConstraintDescription
toStringRequiredRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typeStringRequiredUse location
locationObjectRequiredObject contains location content
location.longitudeStringRequiredLocation’s Longitude
location.latitudeStringRequiredLocation’s Latitude
location.nameStringOptionalName of the Location
location.addressStringOptionalAddress 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 / ObjectData TypeDescription
toStringRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typesStringUse contacts
contactsObjectThis object appears with type:contact. It contains location information
contact.addressesArrayArray of objects. Each Object is Address
contacts.birthdayStringDate of Birth
contacts.emailsArrayArray of Objects. Each Object is an Email Address
contacts.nameObjectName. It breaks down name into parts defined as keys
.orgObjectOrganization
contacts.phonesArrayArray of Objects. Each Objec is a Phone Number
contacts.urlsObjectURL 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 / ObjectData TypeDescription
toStringRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typeStringUse interactive
interactiveObjectThis object appears with type:interactive. It contains interactive button and content information
interactive.typeStringUse button
interacive.bodyObjectBody Object
interactive.body.textStringText of the Body
interactive.actionObjectObject contains Quick Reply Buttons
interactive-action.buttonsArrayIt 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/ObjectData TypeConstraintDescription
typeStringRequiredUse reply
replyObjectRequiredDefine Quick Reply Button
reply.idStringRequiredGive 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.titleStringRequiredLabel 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/ObjectData TypeConstraintDescription
toStringRecipient Phone No. Format: +6599999999 (65 is the Country Code, 99999999 is Phone No.)
typeStringUse interactive
interactiveObjectThis object appears with type:interactive. It contains interactive button and content information
interactive.typeStringUse list
interactive.headerObjectHeader Object
interacive.bodyObjectBody Object
interacive.footerObjectFooter Object
interactive.actionObjectObject contains List Items
interactive.action.buttonStringLabel for the Action Button to open the List
interactive.action.sectionsArrayArray 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/ObjectData TypeConstraintDescription
titleStringRequiredSection Title. This helps to categorize your listed items
rowsArrayRequiredIt defines each listed item in the section in form of an object
rows[n].idStringRequiredGive 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].titleStringRequiredTitle for the listed item
rows[n].descriptionStringOptionalDescription 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
}

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

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