Please refer to support article on Whatsapp Cloud APIs to get more details on our offerings. You can use this sign up page to register yourself to use this feature . If you are an existing customer who needs access to Whatsapp Cloud APIs please drop an email to hello@exotel.com and we will surely assist you.
This API can send messages to a single number with a message content or different numbers with different message contents for each number. To send message through Exotel API, you will need to make a HTTP POST request to
https://<your_api_key>:<your_api_token><subdomain>/v2/accounts/<your_sid>/messages
<your_api_key>
and <your_api_token>
with the API key and token created by you.<your_sid>
with your “Account sid".<subdomain>
with the region of your account
<your_api_key>
, <your_api_token>
and <your_sid>
are available in the API settings page of your Exotel Dashboard
The following are the POST parameters -
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
custom_data |
String |
Optional |
This parameter can be used to send any custom data at the API request level. This will be passed back in the callback. |
status_callback |
String (URL) |
Optional |
Once the message reaches terminal state, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API. |
|
Channel Object |
Optional |
Information related to the messages to be sent out on whatsapp. |
* The Whatsapp parameter mentioned here will be used to send messages through Whatsapp communication channel. In future the API will be extended further to support other communication channels like SMS. Later, SMS parameter can also be passed to send SMSes.
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
custom_data |
String |
Optional |
This parameter can be used to send any custom data at the API request level. This will be passed back in the callback. |
status_callback |
String (URL) |
Optional |
Once the message reaches terminal state, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API. |
messages |
[]Message Object |
Mandatory |
Array of messages to be sent out |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
custom_data |
String |
Optional |
This parameter can be used to send any custom data at the API request level. This will be passed back in the callback. |
status_callback |
String (URL) |
Optional |
Once the message reaches terminal state, Exotel will do a POST callback to your end point if the URL is set as a parameter in the API. |
from |
String |
Mandatory |
From number from which the message has to be sent |
to |
String |
Mandatory |
Phone number of the user to whom a message needs to be sent. The number must be in e.164 format. Here are some examples of supported phone number formats: "+10000000000" "+919888888888" "+919876543210" |
content |
Whatsapp Message Object |
Mandatory |
Whatsapp message body |
This will be similar to Whatsapp Native API contracts [Refer Here]:
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
recepient_type |
String |
Mandatory |
Recipient type of the user to whom message is being sent. Currently, you can only send messages to individuals. Set this as an individual. Default: individual |
type |
String |
Mandatory |
Type of the message. Type can be - Text Image Audio Video Document Sticker Location Contact Interactive - This is for List Messages, Reply Buttons |
text |
Text Object |
Mandatory/Optional |
Mandatory when type is text. To send a text message attach a WhatsappMessageObject with type = text and then add a text object |
image |
Image Object |
Mandatory/Optional |
Mandatory when type is image. To send a image attach a WhatsappMessageObject with type = image and then add a image object |
audio |
Audio Object |
Mandatory/Optional |
Mandatory when type is audio. To send a audio attach a WhatsappMessageObject with type = audio and then add a audio object |
video |
Video Object |
Mandatory/Optional |
Mandatory when type is video. To send a video attach a WhatsappMessageObject with type = video and then add a video object |
document |
Document Object |
Mandatory/Optional |
Mandatory when type is document. To send a sticker attach a WhatsappMessageObject with type = document and then add a document object |
sticker |
Sticker Object |
Mandatory/Optional |
Mandatory when type is sticker. To send a sticker attach a WhatsappMessageObject with type = sticker and then add a sticker object. The type of file should be image/webp. |
location |
Location Object |
Mandatory/Optional |
Mandatory when type is location. To send a location message attach a WhatsappMessageObject with type = location and then add a location object |
contacts |
Contact Object |
Mandatory/Optional |
Mandatory when type is contacts. To send a contact message attach a WhatsappMessageObject with type = contact and then add a contacts object |
interactive |
Interactive Object |
Mandatory/Optional |
Mandatory when type is interactive. To send interactive messages attach a WhatsappMessageObject with type = interactive and then add an interactive object. The components of each interactive object generally follow a consistent pattern: header, body, footer, and action. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
body |
String |
Mandatory |
The text of the text message which can contain URLs which begin with http:// or https:// and formatting. If you include URLs in your text and want to include a preview box in text messages (preview_url: true), make sure the URL starts with http:// or https:// —https:// URLs are preferred. You must include a hostname, since IP addresses will not be matched. Maximum length: 4096 characters. |
preview_url |
Boolean |
Optional |
Set preview_url as ‘Yes’ only if the body includes a URL which begins with https:// or http:// and you want to preview the URL Set preview_url as ‘No’ if you do not want to preview the URL |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
link |
String |
Mandatory |
Link of the image to be sent.Use only with HTTP/HTTPS URLs. |
caption |
String |
Optional |
Caption for the image. Describes the specified image. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
link |
String |
Mandatory |
Link of the audio to be sent.Use only with HTTP/HTTPS URLs. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
link |
String |
Mandatory |
Link of the video to be sent. Use only with HTTP/HTTPS URLs. |
caption |
String |
Optional |
Caption for the video. Describes the specified video media. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
link |
String |
Mandatory |
Link of the document to be sent. Use only with HTTP/HTTPS URLs. |
caption |
String |
Optional |
Caption for the document. Describes the specified document media. |
filename |
String |
Optional |
Describes the filename for the specific document. Use only with document media. The extension of the filename will specify what format the document is displayed as in WhatsApp. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
link |
String |
Mandatory |
Link of the sticker to be sent. Use only with HTTP/HTTPS URLs. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
longitude |
String |
Mandatory |
Longitude of the location |
latitude |
String |
Mandatory |
Latitude of the location |
name |
String |
Optional |
Name of the location |
address |
String |
Optional |
Address of the location. Only displayed if name is present. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
addresses |
[]Address Object |
Optional |
List of addresses |
birthday |
String |
Optional |
Birthday of the contact. YYYY-MM-DD formatted string. |
emails |
[]Email Object |
Optional |
List of emails of the contact. |
name |
Name Object |
Mandatory |
Full contact name of the contact |
org |
Org Object |
Optional |
Organization information of the contact |
phones |
[]Phone Object |
Optional |
Phone number(s) of the contact |
urls |
[]URL Object |
Optional |
URL(s) of the contact |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
city |
String |
Optional |
City name of the address |
country |
String |
Optional |
Full country name of the address |
country_code |
String |
Optional |
Country code of the address. Two-letter country abbreviation. |
state |
String |
Optional |
State of the address. State abbreviation |
street |
String |
Optional |
Street number and name of the address |
type |
String |
Optional |
Type of the address. Standard values are HOME and WORK. |
zip |
String |
Optional |
ZIP code of the address |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
|
String |
Optional |
Email address. |
type |
String |
Optional |
Type of the email. Standard values are HOME and WORK. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
first_name |
String |
Optional |
First Name of the contact |
formatted_name |
String |
Mandatory |
Full name, as it normally appears. |
last_name |
String |
Optional |
Last Name of the contact |
middle_name |
String |
Optional |
Middle Name of the contact |
suffix |
String |
Optional |
Suffix of the contact |
prefix |
String |
Optional |
Prefix of the contact |
*At least one of the optional parameters needs to be included along with the formatted_name parameter.
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
company |
String |
Optional |
Name of the contact's company. |
department |
String |
Optional |
Name of the contact's department. |
title |
String |
Optional |
Contact's business title. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
phone |
String |
Optional |
Phone number of the contact |
type |
String |
Optional |
Standard Values are CELL, MAIN, IPHONE, HOME, and WORK. |
wa_id |
String |
Optional |
Whatsapp Id of the phone number |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
URL |
String |
Optional |
URL of the contact |
type |
String |
Optional |
Standard values are HOME and WORK. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
type |
String |
Optional |
The type of interactive message you want to send. Supported values:
|
header |
Header Object |
Optional |
Header content displayed on top of a message. |
body |
Body Object |
Mandatory/Optional |
Optional for type product. Required for other message types. |
footer |
Footer Object |
Optional |
Footer of the interactive message |
action |
Action Object |
Optional |
Action you want the user to perform after reading the message. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
type |
String |
Mandatory |
The header type you would like to use. Supported values:
|
text |
String |
Mandatory/Optional |
Required if header type is set to text. Text for the header. Formatting allows emojis, but not markdown. Maximum length: 60 characters. |
image |
Image Object |
Mandatory/Optional |
Required if header type is set to image. |
video |
Video Object |
Mandatory/Optional |
Required if header type is set to video. |
document |
Document Object |
Mandatory/Optional |
Required if header type is set to document. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
text |
String |
Mandatory |
Required if body is present. The content of the message. Emojis and markdown are supported. Maximum length: 1024 characters. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
text |
String |
Mandatory |
Required if footer is present. The footer content. Emojis, markdown, and links are supported. Maximum length: 60 characters. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
button |
String |
Mandatory |
Required for List Messages. Button content. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. |
sections |
[]Section Object |
Mandatory/Optional |
Sections of action (To send Interactive List message). Required for List Messages. Array of section objects. Minimum of 1, maximum of 10. |
buttons |
[]Button Object |
Mandatory/Optional |
Button of the action (To send Interactive Button message).Required for Reply Buttons.You can have up to 3 buttons. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
title |
String |
Mandatory/Optional |
Title of the section.Required if the message has more than one section. Maximum length: 24 characters. |
rows |
[]Row Object |
Mandatory |
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 Name |
Parameter Type |
Mandatory/Optional |
Value |
id |
String |
Mandatory |
ID of the row |
title |
String |
Mandatory |
Title of the row |
description |
String |
Optional |
Description of the row |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
type |
String |
Mandatory |
Type of the Button. Only supported type is reply (for Reply Button) |
reply |
ReplyObject |
Mandatory |
Information to be added to the button. |
Parameter Name |
Parameter Type |
Mandatory/Optional |
Value |
id |
String |
Mandatory |
ID of the information. Unique identifier for your button. This ID is returned in the webhook when the button is clicked by the user. Maximum length: 256 characters. You cannot have leading or trailing spaces when setting the ID. |
title |
String |
Mandatory |
Title of the information. It cannot be an empty string and must be unique within the message. Emojis are supported, markdown is not. Maximum length: 20 characters. |
Please refer Exotel's sample postman collection to try out the APIs, we have also shared some examples here for your reference.
curl -XPOST "https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages" -d '{ "custom_data": "Order12", "status_callback": "https://webhook.site", "whatsapp": { "custom_data": "Order12", "status_callback": "https://webhook.site", "messages": [ { "custom_data": "Order12", "status_callback": "https://webhook.site", "from": "+919999XXXXXX", "to": "++919999XXXXXX", "content": { "recipient_type": "individual", "type": "text", "text": { "preview_url": false, "body": "MESSAGE_CONTENT" } } }, { "custom_data": "Order12", "status_callback": "https://webhook.site", "from": "+919999XXXXXX", "to": "+919999XXXXXX", "Content": { "recipient_type": "individual", "type": "text", "text": { "preview_url": false, "body": "MESSAGE_CONTENT" } } } ] } }'
var https = require('follow-redirects').https; var fs = require('fs'); var qs = require('querystring'); var options = { 'method': 'POST', 'hostname': '<api_key>', 'port': <api_token><subdomain>, 'path': '/v2/accounts/<your_sid>/messages', 'headers': { 'Content-Type': 'application/x-www-form-urlencoded' }, 'maxRedirects': 20 }; var req = https.request(options, function (res) { varchunks= []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { varbody=Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); var postData = qs.stringify({ '{\n "custom_data": "Order12",\n "status_callback": "https://webhook.site",\n "whatsapp": {\n "custom_data": "Order12",\n "status_callback": "https://webhook.site",\n "messages": [\n {\n "custom_data": "Order12",\n "status_callback": "https://webhook.site",\n "from": "+919999XXXXXX",\n "to": "+919999XXXXXX",\n "content": {\n "recipient_type": "individual",\n "type": "text",\n "text": {\n "preview_url": false,\n "body": "MESSAGE_CONTENT"\n }\n }\n },\n {\n "custom_data": "Order12",\n "status_callback": "https://webhook.site",\n "from": "+919999XXXXXX",\n "to": "+919999XXXXXX",\n "Content": {\n "recipient_type": "individual",\n "type": "text",\n "text": {\n "preview_url": false,\n "body": "MESSAGE_CONTENT"\n }\n }\n }\n ]\n }\n }': '' }); req.write(postData); req.end();
<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://%3Capi_key%3E:%3Capi_token%3E%3Csubdomain%3E/v2/accounts/%3Cyour_sid%3E/messages', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS => '%7B%0A%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%22whatsapp%22%3A%20%7B%0A%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%22messages%22%3A%20%5B%0A%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22from%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22to%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22recipient_type%22%3A%20%22individual%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22text%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22preview_url%22%3A%20false%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22body%22%3A%20%22MESSAGE_CONTENT%22%0A%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%20%20%20%22from%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%22to%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%22Content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22recipient_type%22%3A%20%22individual%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22text%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22preview_url%22%3A%20false%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22body%22%3A%20%22MESSAGE_CONTENT%22%0A%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%5D%0A%20%20%20%7D%0A%20%7D=', CURLOPT_HTTPHEADER => array( 'Content-Type: application/x-www-form-urlencoded' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;
import requests url = "https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages" payload='%7B%0A%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%22whatsapp%22%3A%20%7B%0A%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%22messages%22%3A%20%5B%0A%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22from%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22to%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22recipient_type%22%3A%20%22individual%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22text%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22preview_url%22%3A%20false%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22body%22%3A%20%22MESSAGE_CONTENT%22%0A%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%20%20%20%22from%22%3A%20%22%2B919945566772%22%2C%0A%20%20%20%20%20%20%20%20%20%22to%22%3A%20%22%2B919988998899%22%2C%0A%20%20%20%20%20%20%20%20%20%22Content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22recipient_type%22%3A%20%22individual%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22text%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22preview_url%22%3A%20false%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22body%22%3A%20%22MESSAGE_CONTENT%22%0A%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%5D%0A%20%20%20%7D%0A%20%7D=' headers = { 'Content-Type': 'application/x-www-form-urlencoded' } response = requests.request("POST", url, headers=headers, data=payload) print(response.text)
require "uri" require "net/http" url = URI("https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/x-www-form-urlencoded" request.body = "%7B%0A%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%22whatsapp%22%3A%20%7B%0A%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%22messages%22%3A%20%5B%0A%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22from%22%3A%20%22%2B9199XXXXXXXX2%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22to%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%20%22content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22recipient_type%22%3A%20%22individual%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22text%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22preview_url%22%3A%20false%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%20%22body%22%3A%20%22MESSAGE_CONTENT%22%0A%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%7D%2C%0A%20%20%20%20%20%20%20%7B%0A%20%20%20%20%20%20%20%20%20%22custom_data%22%3A%20%22Order12%22%2C%0A%20%20%20%20%20%20%20%20%20%22status_callback%22%3A%20%22https%3A%2F%2Fwebhook.site%22%2C%0A%20%20%20%20%20%20%20%20%20%22from%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%22to%22%3A%20%22%2B9199XXXXXXXX%22%2C%0A%20%20%20%20%20%20%20%20%20%22Content%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22recipient_type%22%3A%20%22individual%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22type%22%3A%20%22text%22%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22text%22%3A%20%7B%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22preview_url%22%3A%20false%2C%0A%20%20%20%20%20%20%20%20%20%20%20%20%20%22body%22%3A%20%22MESSAGE_CONTENT%22%0A%20%20%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%20%20%7D%0A%20%20%20%20%20%5D%0A%20%20%20%7D%0A%20%7D=" response = https.request(request) puts response.read_body
curl -XPOST "https://<api_key>:<api_token><subdomain>/v2/accounts/<your_sid>/messages" -d '{ "custom_data": "ORDER126", "status_callback": "https://webhook.site/", "whatsapp": { "messages": [ { "from": "9199XXXXXXXX", "to": "9199XXXXXXXX", "content": { "type": "image", "image": { "link": "https://image.587.jpg", "caption": "This is image caption" } } } ] } }'
var https = require('follow-redirects').https; var fs = require('fs'); var options = { 'method': 'POST', 'hostname': '{{Host}}', 'path': '/v2/accounts/{{AccountSid}}/messages', 'headers': { 'Content-Type': 'application/json' }, 'maxRedirects': 20 }; var req = https.request(options, function (res) { var chunks = []; res.on("data", function (chunk) { chunks.push(chunk); }); res.on("end", function (chunk) { var body = Buffer.concat(chunks); console.log(body.toString()); }); res.on("error", function (error) { console.error(error); }); }); var postData = JSON.stringify({ "custom_data": "ORDER126", "status_callback": "https://webhook.site/", "whatsapp": { "messages": [ { "from": "9199XXXXXXXX", "to": "9199XXXXXXXX", "content": { "type": "image", "image": { "link": "https://image.587.jpg", "caption": "This is image caption" } } } ] } }); req.write(postData); req.end();
<?php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://%7B%7BAccountSid%7D%7D:%7B%7BAccountToken%7D%7D@%7B%7BHost%7D%7D/v2/accounts/%7B%7BAccountSid%7D%7D/messages', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'POST', CURLOPT_POSTFIELDS =>'{ "custom_data": "ORDER126", "status_callback": "https://webhook.site/", "whatsapp": { "messages": [ { "from": "9199XXXXXXXX", "to": "9199XXXXXXXX", "content": { "type": "image", "image": { "link": "https://image.587.jpg", "caption": "This is image caption" } } } ] } }', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json' ), )); $response = curl_exec($curl); curl_close($curl); echo $response;
import requests
import json
url = “https://{{AccountSid}}:{{AccountToken}}@{{Host}}/v2/accounts/{{AccountSid}}/messages”
payload = json.dumps({
“custom_data”: “ORDER126”,
“status_callback”: “https://webhook.site/”,
“whatsapp”: {
“messages”: [
{
“from”: “9199XXXXXXXX”,
“to”: “9199XXXXXXXX”,
“content”: {
“type”: “image”,
“image”: {
“link”: “https://image.587.jpg”,
“caption”: “This is image caption”
}
}
}
]
}
})
headers = {
‘Content-Type’: ‘application/json’
}
response = requests.request(“POST”, url, headers=headers, data=payload)
print(response.text)
require "uri" require "json" require "net/http" url = URI("https://{{AccountSid}}:{{AccountToken}}@{{Host}}/v2/accounts/{{AccountSid}}/messages") https = Net::HTTP.new(url.host, url.port) https.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = "application/json" request.body = JSON.dump({ "custom_data": "ORDER126", "status_callback": "https://webhook.site/", "whatsapp": { "messages": [ { "from": "9199XXXXXXXX", "to": "9199XXXXXXXX", "content": { "type": "image", "image": { "link": "https://image.587.jpg", "caption": "This is image caption" } } } ] } }) response = https.request(request) puts response.read_body
HTTP Response:
{ "request_id": "b434e927a5844175b23059cd96feea3d", "method": "POST", "http_code": 202, "metadata": { "failed": 0, "total": 1, "success": 1 }, "response": { "whatsapp": { "messages": [ { "code": 202, "error_data": null, "status": "success", "data": { "sid": "2FdiiEQUosckPhpZfuVwfjxiSlc16a4", } } ] } } }
The following are the response parameters -
Parameter |
Type |
Mandatory/Optional |
Notes |
request_id |
String |
Mandatory |
This indicates the unique id of the request. Useful for debugging and tracing purposes. |
method |
String |
Mandatory |
This indicates the HTTP method for the request such as POST |
http_code |
Integer |
Mandatory |
This indicates the HTTP code for the request such as 202, 400, 500 etc. |
metadata |
Metadata Object |
Mandatory |
Metadata pertaining to the request. Count of failed, total and success records. |
response |
Response Object |
Mandatory |
Response for the request |
Parameter |
Type |
Mandatory/Optional |
Notes |
total |
Integer |
Mandatory |
Total number of the messages in the request |
success |
Integer |
Mandatory |
Number of messages successfully accepted |
failed |
Integer |
Mandatory |
Number of messages that couldn’t be accepted (failed) |
Parameter |
Type |
Mandatory/Optional |
Notes |
|
Channel Response Object |
Mandatory |
Response for Whatsapp messages specified in the request |
Parameter |
Type |
Mandatory/Optional |
Notes |
messages |
[]Create Message Response Object |
Mandatory |
Array of messages response for each message |
Parameter |
Type |
Mandatory/Optional |
Notes |
code |
Integer |
Mandatory |
Response code for the individual message |
error_data |
Error Response Object |
Optional |
Error related to a single message |
status |
String |
Mandatory |
Status of the single message |
data |
Message Response Object |
Optional |
Data pertaining to a single message |
Parameter |
Type |
Mandatory/Optional |
Notes |
code |
Numeric |
Mandatory |
Numeric HTTP code for a Single message |
message |
String |
Mandatory |
Brief description of the error |
description |
String |
Mandatory |
Detailed explanation of error |
Parameter |
Type |
Mandatory/Optional |
Notes |
sid |
String |
Mandatory |
SID (Unique identifier) of the single message |
HTTP Error Codes |
Error Message |
202 |
Accepted - Request accepted. |
400 |
Bad Request - Something in your header or request body was malformed/missing. More than 100 messages specified in a request |
401 |
Unauthorized - Necessary credentials were either missing or invalid. |
402 |
Payment Required - The action is not available on your plan, or you have exceeded usage limits for your current plan. |
403 |
Your credentials are valid, but you don’t have access to the requested resource. |
404 |
Not Found - The object you’re requesting doesn’t exist. |
5xx |
Server Errors - Something went wrong at our end. Please try again. |
Status callback URL can be passed in status_callback parameter in send message/template message APIs and it can also be configured as default to receive the responses. Exotel team will help you configure the default URL while onboarding.
*NOTE: Any callback can be received only in one status callback URL at any time
"whatsapp": { "messages": [ { "callback_type": "dlr", "sid": "1234", "to": "2365564965", "exo_status_code": 25001, "exo_detailed_status": "EX_MESSAGE_DELIVERED", "description": "Message delivered", "timestamp": "2022-12-07T17:00:00.000+05:30", "custom_data": "custom" } ] } }
The following are the status callback parameters -
Parameter |
Type |
Mandatory |
Notes |
|
Message DLR Object |
Optional |
Delivery report (DLR) of the Whatsapp channel |
Parameter |
Type |
Mandatory |
Notes |
messages |
[]Whatsapp Message DLR Object |
Mandatory |
Information relating to the messages for DLR |
Parameter |
Type |
Mandatory |
Notes |
callback_type |
String |
Mandatory |
Type of the callback. Possible values: dlr, icm |
sid |
String |
Mandatory |
SID (Unique Identifier) of the message |
to |
String |
Mandatory |
Phone Number of the user to whom the message was sent. |
exo_status_code |
Integer |
Mandatory |
ExoStatusCode for the message |
exo_detailed_status |
String |
Mandatory |
Detailed status of ExoStatus code |
description |
String |
Mandatory |
Description of the ExoStatus code |
timestamp |
String |
Mandatory |
Timestamp at which the event occurred |
custom_data |
String |
Optional |
It will return the custom data, if the same was passed in the API request |
Detailed Status Code |
Detailed Status |
Description |
30001 |
EX_MESSAGE_SENT |
The message has been sent to the user |
30002 |
EX_MESSAGE_DELIVERED |
The message has been successfully delivered to the user |
30003 |
EX_MESSAGE_SEEN |
The message has been seen by the user |
30004 |
EX_SYSTEM_ERROR |
The message failed due to an issue with the system. For eg: Authentication/Access Token/Permission related issue, service not available issue etc. |
30005 |
EX_NUMBER_ERROR |
The message failed due to an issue with the phone number |
30006 |
EX_SETUP_ERROR |
The message failed due to set-up error |
30007 |
EX_RATE_LIMIT_HIT |
The message failed due to a breach in rate limit |
30008 |
EX_SPAM_RATE_LIMIT_HIT |
The message failed as spam rate limit has been breached |
30009 |
EX_TOO_MANY_REQUEST |
The message failed as too many request has been made in short span |
30010 |
EX_INVALID_REQUEST |
The message failed as the request is invalid |
30011 |
EX_UNKNOWN_ERROR |
The message failed due to an unknown error |
30012 |
EX_INVALID_RECIPIENT |
The message failed as the recipient was invalid |
30013 |
EX_INCAPABLE_RECIPIENT |
The message failed as the recipient is unable to receive the message |
30014 |
EX_RECIPIENT_BLOCKED |
The message failed as the recipient is not in allowed list |
30015 |
EX_UNSUPPORTED_MESSAGE |
The message failed as unsupported message type has been passed in the request body |
30016 |
EX_MEDIA_DOWNLOAD_ERROR |
The message failed as Whatsapp is unable to download the sender media |
30017 |
EX_MEDIA_UPLOAD_ERROR |
The message failed as unsupported media type has been passed in the request body |
30018 |
EX_REENGAGEMENT_ERROR |
The message failed as 24 hours window of the conversation is over |
30019 |
EX_INVALID_PARAM |
The message failed as invalid parameters has been passed in the request body |
30020 |
EX_MISSING_PARAM |
The message has failed as mandatory parameter is missing from the request body |
30021 |
EX_INVALID_PARAM_VALUE |
The message failed as invalid parameter value has been passed in the request body |
30022 |
EX_TEMPLATE_ERROR |
The message failed as the template format char policy has been violated |
30023 |
EX_TEMPLATE_PARAM_ERROR |
The message failed due to mismatch in count of template parameters |
30024 |
EX_TEMPLATE_NOT_FOUND |
The message failed as the passed message template does not exist |
30025 |
EX_TEMPLATE_TEXT_TOO_LONG |
The message failed as the translated text from template message is too long |
30026 |
EX_INVALID_TEMPLATE_NAMESPACE |
The message failed as invalid template namespace has been passed |
30027 |
EX_MESSAGE_PENDING_TOO_LONG |
The message failed as the message was pending for too long |
30028 |
EX_MESSAGE_EXPIRED |
The message failed as the message got expired |
30029 |
EX_MESSAGE_TOO_LONG |
The message failed as the number of characters in the message was more than 4096 characters |
30030 |
EX_WEBHOOK_ERROR |
Webhook is not configured |
30031 |
EX_SECTION_COUNT_ERROR |
The message failed due to invalid no. of sections |
30032 |
EX_ROWS_COUNT_ERROR |
The message failed due to invalid no. of rows |
30033 |
EX_PRODUCT_COUNT_ERROR |
The message failed due to invalid no. of product |
30034 |
EX_CATALOGUE_NOT_FOUND |
The message failed as the catalog ID has not been found |
30035 |
EX_CATALOGUE_NOT_LINKED |
The message failed as the catalog ID has not been linked to the API number |
30036 |
EX_MISSING_PRODUCT |
The message failed as the product is missing in the catalog |
30037 |
EX_PRODUCT_NOT_FOUND |
The message failed as all the products in the request body has not been found in the product catalog |
30038 |
EX_PRODUCT_COMPLIANCE_ERROR |
The message failed as the listed products failed compliance |
30039 |
EX_INVALID_HEADER |
The message failed due to invalid header structure |
30040 |
EX_MISSING_COMPLIANCE |
The message failed as compliance information was missing |
30041 |
EX_CHAR_POLICY_VIOLATION |
The message failed as character policy got violated |