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 / 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 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 / 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 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
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.) |
types | String | Use contacts |
contacts | Object | This object appears with type:contact . It contains location information |
contact.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 |
.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/Object | Data Type | 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 | Constraint | 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}
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. |