Send Free-form Whatsapp Messages
You can use our business messaging API to send free-form messages of types:
- Text messages
- Reaction message
- Media messages
- Location messages
- Contact messages
- Interactive messages
Note: Before starting, it is recommended to go through the basics of whatsapp message
Endpoint
Header
Authentication
AUTHORIZATION: Bearer Token
Body
Object
{
"messages": [
{
"originator": "{registered phone_number}",
"content": {
"message_type": "<TYPE>",
/* FOR TEXT MESSAGES ONLY */
"text": {<TEXT>}
/* FOR REACTION MESSAGES ONLY */
"reaction": {<REACTION>}
/* FOR ATTACHMENT MESSAGES ONLY */
"attachment": {<MEDIA>}
/* FOR LOCATION MESSAGES ONLY */
"location": {<LOCATION>}
/* FOR CONTACTS MESSAGES ONLY */
"contacts": {<CONTACTS>}
/* FOR INTERACTIVE MESSAGES ONLY */
"interactive": {<INTERACTIVE>}
},
"recipients": [<recipient>],
"report_url": "{report url}"
}
]
}
Body parameters
Parameter | Type | Description |
---|---|---|
* originator | String | The Phone number of Sender/Header of a message. We can use your mobile number that is registered and approved in meta. |
* recipients | Array(Object) | Array of recipient object |
*message_type | String | Possible types in free-form message are: TEXT, REACTION, ATTACHMENT, LOCATION, CONTACTS, INTERACTIVE |
* text | TEXT object | If message type is text, then add, text object |
* reaction | REACTION object | If message type is reaction, then add reaction object |
* attachment | MEDIA object | If message type is attachment, then add media object |
* location | LOCATION object | If message type is location, then add location object |
* contacts | CONTACTS object | If message type is contacts, then add contacts object |
* interactive | INTERACTIVE object | If message type is interactive, then add interactive object |
report_url | HttpUrl | To receive delivery status (DLR) for your message, specify the callback server URL where you want to receive the message status updates using the report_url parameter. When the delivery status changes, the status updates will be sent to the specified URL. See more |
Message Objects
"recipients": [
{
"recipient": "{{recipient1}}",
"recipient_type": "individual",
"reference": {
"cust_ref": "[email protected]",
"message_tag1": "d7id00001_m1",
"conversation_id": "d7id00001"
}
},
{
"recipient": "{{recipient2}}",
"recipient_type": "individual",
"reference": {
"cust_ref": "[email protected]",
"message_tag1": "d7id00001_m1",
"conversation_id": "d7id00001"
}
}
],
Parameter | Type | Description | Value / Pattern |
---|---|---|---|
*recipient | Array(string) | Mobile Numbers to send Whatsapp seperated by comma in an array. The recipient's phone number should have a country code prefix. | +97156xxxxxxx |
*recipient_type | String | Default: individual. Now Support Only individual recipients | individual |
cust_ref | string | Any text to store reference of recipient | [email protected] |
message_tag1 | string | Any text tag for message reference | tag1 |
message_tag2 | string | Any text tag for message reference | tag2 |
message_tag3 | string | Any text tag for message reference | tag3 |
message_tag4 | string | Any text tag for message reference | tag4 |
message_tag5 | string | Any text tag for message reference | tag5 |
conversation_id | string | Any text for conversation reference | conversation_marketing |
Parameter | Type | Description | Value / Pattern |
---|---|---|---|
*body | String | Contains the text of the message, which can contain URLs and formatting. Maximum length: 4096 characters | Hi, How can I help you? |
preview url | Boolean | Set to true to have the WhatsApp Messenger and WhatsApp Business apps attempt to render a link preview of any URL in the body text string. URLs must begin with http:// or https://. If multiple URLs are in the body text string, only the first URL will be rendered. If preview_url is omitted, or if unable to retrieve a preview, a clickable link will be rendered instead. |
Formatting | Symbol | Example |
---|---|---|
Bold | Asterisk (*) | Your total is $10.50 |
Italics | Underscore (_) | Welcome to WhatsApp! |
Tilde (~) | This is ~better~ best! | |
Code | Three backticks (```) | ```print 'Hello World';``` |
Parameter | Type | Description |
---|---|---|
*message_id | String | The WhatsApp Message ID (wamid) of the message on which the reaction should appear. The reaction will not be sent if the message is, older than 30 days, a reaction message or has been deleted. Also,if the ID is of a message that has been deleted, the message will not be delivered. |
*emoji | String | Emoji to appear on the message. |
"attachment": {
"type": "image",
"caption": "Natural Beauty",
"url": "https://miro.medium.com/max/780/1*9Wdo1PuiJTZo0Du2A9JLQQ.jpeg"
}
Parameter | Type | Description |
---|---|---|
*type | String | Type of the attachment you want to send. Supported Values: image, audio, document, video, sticker. |
*url | String | URL for the attachment. The protocol and URL of the media to be sent. Use only with HTTP/HTTPS URL. |
caption | String | Caption for the attachment. Do not use caption with audio or sticker media. |
filename | String | Use filename only with document. |
"location": {
"longitude": 77.6109,
"latitude": 12.9379,
"name": "KARXX XX PRIVATE LIMITED",
"address": " 30, Hosur Main Road"
}
Parameter | Type | Description |
---|---|---|
*longitude | String | Longitude of the Location you wants to send. |
*latitude | String | Longitude of the Location you wants to send. |
name | String | Name of the Location you wants to send. |
address | String | Address of the Location you wants to send. Only displayed if the name is present. |
"contacts": [
{
"addresses": [{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "HOME"
},
{
"street": "STREET",
"city": "CITY",
"state": "STATE",
"zip": "ZIP",
"country": "COUNTRY",
"country_code": "COUNTRY_CODE",
"type": "WORK"
}],
"birthday": "YEAR_MONTH_DAY",
"emails": [{
"email": "EMAIL",
"type": "WORK"
},
{
"email": "EMAIL",
"type": "HOME"
}],
"name": {
"formatted_name": "NAME",
"first_name": "FIRST_NAME",
"last_name": "LAST_NAME",
"middle_name": "MIDDLE_NAME",
"suffix": "SUFFIX",
"prefix": "PREFIX"
},
"org": {
"company": "COMPANY",
"department": "DEPARTMENT",
"title": "TITLE"
},
"phones": [{
"phone": "PHONE_NUMBER",
"type": "HOME"
},
{
"phone": "PHONE_NUMBER",
"type": "WORK",
"wa_id": "PHONE_OR_WA_ID"
}],
"urls": [{
"url": "URL",
"type": "WORK"
},
{
"url": "URL",
"type": "HOME"
}]
}
]
Parameter | Type | Description |
---|---|---|
*name | Object | Full contact name formatted as a name object. |
addresses | Array (Object) | Full contact address(es) formatted as an addresses object. |
birthday | String | YYYY-MM-DD formatted string. |
emails | Array (Object) | Contact email address(es) formatted as an emails object. |
org | Object | Contact organization information formatted as an org object. |
phones | Array (Object) | Contact phone number(s) formatted as a phone object. |
urls | Array (Object) | Contact URL(s) formatted as a urls object. |
Parameter | Type | Description |
---|---|---|
*formatted_name | String | Full name, as it normally appears. At least one of the optional parameters needs to be included along with the formatted_name parameter. |
first_name | String | First name of the contact you wants to send. |
last_name | String | Last name of the contact you wants to send. |
middle_name | String | Middle name of the contact you wants to send. |
suffix | String | Name suffix. |
prefix | String | Name prefix. |
Parameter | Type | Description |
---|---|---|
street | String | Street number and name. |
city | String | City name. |
state | String | State abbreviation. |
zip | String | Zip Code |
country | String | Full country name. |
country_code | String | Two-letter country abbreviation. |
type | String | Standard values are HOME and WORK. |
Parameter | Type | Description |
---|---|---|
String | Email Address. | |
type | String | Supported values are HOME and WORK. |
Parameter | Type | Description |
---|---|---|
company | String | Name of the contact's company. |
department | String | Name of the contact's department. |
title | String | Contact's business title. |
Parameter | Type | Description |
---|---|---|
phone | String | Automatically populated with the wa_id value as a formatted phone number. |
type | String | Standard Values are CELL, MAIN, IPHONE, HOME, and WORK. |
wa_id | String | WhatsApp ID. |
Parameter | Type | Description |
---|---|---|
url | String | URL. |
type | String | Supported values are HOME and WORK. |
See Interactive object details here
Parameter | Type | Description |
---|---|---|
*type | String | The type of interactive message you want to send. Supported values: button, list |
*body | Object | The body object contains text parameter. Its required if body is present. The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. |
footer | Object | The footer object contains text field. Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length: 60 characters. |
header | Object | Optional. Header content displayed on top of a message. |
*action | Object | Action you want the user to perform after reading the message. |
Parameter | Type | Description |
---|---|---|
type | String | The header type you would like to use. Supported values: text- Used for List Messages & Reply Buttons, video- Used for Reply Buttons, image- Used for Reply Buttons, document- Used for Reply Buttons. |
document | Object | Required if type is set to document. Contains two parameters filename and link. |
image | Object | Required if type is set to image. Contains only link parameter. |
text | String | Required if type is set to text. Text for the header. Formatting allows emojis, but not markdown. Maximum length: 60 characters. |
video | Object | Required if type is set to video. Contains only link parameter. |
Parameter | Type | Description |
---|---|---|
button | String | Required. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. |
sections | Array(Object) | Required. Array of section objects. Minimum of 1, maximum of 10. A section object can contain following parameters, title - Required if the message has more than one section. Title of the section. Maximum length: 24 characters. rows - Contains a list of rows. You can have a total of 10 rows across your sections. Each row must have a title (Maximum length: 24 characters) and an ID (Maximum length: 200 characters). You can add a description (Maximum length: 72 characters), but it is optional. |
Parameter | Type | Description |
---|---|---|
buttons | Array(Object) | Required for Reply Buttons. You can have up to 3 buttons. You cannot have leading or trailing spaces when setting the ID. A button object can contain the following parameters: type: only supported type is reply (for Reply Button) title: Button title. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. id: Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. |
CTA URL buttons allow you to map any URL to a button so you don't have to include the raw URL in the interactive message body.
Parameter | Type | Description |
---|---|---|
parameters | Array(Object) | Required for Call-to-Action Buttons. You can have up to one button. Parameters Object should contain the following parameters: display_text: Button text. url: URL to load in the device's default web browser when tapped by the WhatsApp user. |
Response
When the request is validated, request_id, status and created time will be returned. Users can use this request_id to query status using the Get status endpoint.
200 - Success
401 - Unauthorized
404 - Not Found
Response Parameters
Parameter | Value / Pattern |
---|---|
request_id | Unique id for each Whatsapp message request. This request_id is required to check delivery status of your Whatsapp message. |
status | The status of Whatsapp message request. Possible request status are accepted and rejected |
created_at | Date and time of the Whatsapp message request. |
Programing Examples:
1. Text message
2. Reaction message
3. Media message
Media type: Image
Media type: Video
|
|
|
|
|
Media type: Document
|
|
|
|
|
Media type: Audio
Media type: Sticker
|
|
|
|
|
4. Location message
|
|
|
|
|
5. Contact message
|
|
|
|
|
|
|
|
|
|
6. Interactive message
Interactive messages can be categorized into three, based on action object as follows:
- Interactive message with type- cta_url
- Interactive message with type- button
- Interactive message with type- list
Interactive message with type- cta_url and button can have subtypes according to the header object. Header object can be: text, image, video or document
The Interactive message with type list can only have header type text.
Header Object