Whatsapp For Business API
Whatsapp For Business API
Channel Info
PARAMETERS
| Name |
Description |
type |
Required |
| channels |
This block contains information related messaging channel |
N/A |
Yes |
| name |
Name of Messaging Channel. Ex: whatsapp |
string |
Yes |
| from |
Sender or From Number |
number |
Yes |
| meta |
This block contains additional information related to messaging channel |
map |
No |
| recipient |
This block contains contacts information related to channel |
N/A |
Yes |
| foreign_id |
Custom id for reference from customer. |
string |
No |
| group_id |
Segment id which contain list of phone numbers |
string or array |
Yes if to param not present |
| tags |
opt-out the message based on the tags. |
string |
No |
| to |
Receiver mobile numbers : text |
array |
Yes, if group_id not present |
Note : The recipient block inside channel is related to particular communication channel and it is optional. The outside recipient channel contain common recipients for every channel.
{
"channels": [{
"name": "whatsapp",
"from": "91901912xxxx",
"meta" : {
"foreign_id":"your-custom-id",
"tags": ["tag1", "tag2"]
}
}]
"recipient": {
"group_id": "{segment_id}",
"to": ["91XXXXXX", "91XXXXXX"]
}
}
Example Response
{
"status": "OK",
"message": "Message Queued successfully",
"data": [
{
"id": "a418d672-9781-4d97-b517-a56f7d95ad8a",
"channel": "whatsapp",
"from": "919019120xxx",
"to": "9190199xxxxx",
"credits": 1,
"created_at": "2021-06-18T14:48:06.886358Z",
"status": "queued",
"foreign_id": "your-message-id"
}
]
}
HTTP Methods
It will support only POST requests.
API Endpoint
http://portal.thundersms.com/api/v2/
Note: Few elements in the endpoint may change from service to service.
Sending Text Message
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| to |
Destination mobile number with country code |
NA |
Yes |
| payload |
Message Payload section |
N/A |
Yes |
| text |
Message Content you want to send |
Max 4096 Characters |
Yes |
Example Request With Text Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "text",
"payload": {
"text": "This is a simple text message from whatsapp channel"
}
}
}'
Send Image Message
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| url |
Public url of the image file. Either HTTP/HTTPS link. |
5 MB |
Yes |
| thumbnail |
Public url of the thumbnail of the image file. |
N/A |
Yes |
| type |
image/jpg, image/jpeg and image/png |
YES |
YES |
| caption |
some text for image caption |
N/A |
No |
| filename |
Media file name |
N/A |
No |
| pixels |
vertically crops images with the 1:91:1 aspect ratio: 800×418 pixels. To communicate effectively, design the image such that the crux information is at the center of the image. |
YES |
YES |
Example Request With Image Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "image",
"payload": {
"url": "https://picsum.photos/id/237/200/300",
"thumbnail": "https://picsum.photos/id/237/200/300",
"caption": "some caption for document",
"filename": "Sample Image file"
}
}
}'
Send Document Message
We can send Document which is having valid MIME-type as attachment using below API. So anything not image, audio or video will be transmitted as document message.
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| url |
Public url of the document file. Either HTTP or HTTPS link. |
Max File size 100MB |
Yes |
| type |
Any valid MIME-type |
N/A |
No |
| caption |
some text for document caption |
N/A |
No |
| filename |
Media file name |
N/A |
No |
Example Request With Document Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "document",
"payload": {
"url": "http://www.africau.edu/images/default/sample.pdf",
"caption": "some caption for document",
"filename": "Sample PDF file"
}
}
}'
Send Audio Message
We can send Audio clips as attachment using below API.
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| url |
Public url of the audio file. Either HTTP or HTTPS link. |
Upto 16MB |
Yes |
| type |
audio/aac, audio/mp4, audio/amr, audio/mpeg; codecs=opus. (The base audio/ogg type is not supported.) |
YES |
YES |
| caption |
some text for audio caption |
N/A |
No |
| filename |
Media file name |
N/A |
No |
Example Request With Audio Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "audio",
"payload": {
"url": "https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_700KB.mp3",
"caption": "some caption for document",
"filename": "Sample Audio file"
}
}
}'
Send Video Message
We can send Video clips as attachment using below API.
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| url |
Public url of the video file. Either HTTP or HTTPS link. |
Upto 16MB |
Yes |
| type |
video/mp4, video/3gpp (Only H.264 video codec and AAC audio codec is supported.) |
YES |
Yes |
| caption |
some text for audio caption |
N/A |
No |
| filename |
Media file name |
N/A |
No |
Example Request With Video Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "video",
"payload": {
"url": "https://www.learningcontainer.com/wp-content/uploads/2020/05/sample-mp4-file.mp4",
"caption": "some caption for document",
"filename": "Sample video file"
}
}
}'
Send Notification With Interactive Suggestions
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| choices |
this block contains options list of the message |
N/A |
Yes |
| payload.type |
if reply message type value should be reply, or list message type value should be list |
N/A |
Yes |
| choices.type |
if reply message type value should be reply, or list message type value first object should be button and second object should be section |
N/A |
Yes |
Example Request With Interactive Reply Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "interactive",
"payload": {
"type": "reply",
"header": {
"type": "text",
"payload": {
"text": "Hello Dear!"
}
},
"body": {
"type": "text",
"payload": {
"text": "Do you like the whatsapp?"
}
},
"choices": [
{
"type": "reply",
"payload": {
"title": "Yes",
"id": "1"
}
},
{
"type": "reply",
"payload": {
"title": "No",
"id": "2"
}
}
]
}
}
}'
Example Request With Interactive List Messages
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "interactive",
"payload": {
"type": "list",
"header": {
"type": "text",
"payload": {
"text": "Hi Dear!"
}
},
"body": {
"type": "text",
"payload": {
"text": "Do you like whatsapp?"
}
},
"choices": [
{
"type": "button",
"payload": {
"title": "Please Choose",
"rows": [
{
"id": "15",
"title": "first product",
"description": "row-description-content-here"
}
]
}
},
{
"type": "section",
"payload": {
"title": "Choose Anyone",
"rows": [
{
"id": "16",
"title": "Yes",
"description": "I like whatsapp"
},
{
"id": "17",
"title": "No",
"description": "I do not like whatsapp"
}
]
}
}
]
}
}
}'
Send Vcard / Contacts Message
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| phone |
Mobile numbers saved in mobile |
N/A |
Yes |
| name |
Person name |
N/A |
Yes |
| address |
Address details of the contact |
N/A |
Yes |
| org |
Organization details of the contact |
N/A |
Yes |
| emails |
emails details of the contact |
N/A |
Yes |
| urls |
urls details of the contact |
N/A |
Yes |
| birthday |
birthday details of the contact |
N/A |
No |
Example Request With Vcard Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message": {
"type": "contacts",
"payload": {
"addresses": [
{
"city": "Bangalore",
"country": "India",
"country_code": "in",
"state": "KA",
"type": "Office",
"zip": "560078"
}
],
"phones": [
{
"phone": "91901912xxxx",
"type": "HOME"
}
],
"emails": [
{
"email": "hello@domin-name.com",
"type": "WORK"
}
],
"urls": [
{
"url": "https://www.domin-name.com",
"type": "WORK"
}
],
"name": {
"first_name": "Laxman",
"formatted_name": "Laxman Ka",
"last_name": "Ka"
},
"org": {
"company": "Company Name",
"department": "Product",
"title": "Manager"
},
"birthday": "1993-08-18"
}
}
}'
Send Location Message
{endpoint}whatsapp/message/send
PARAMETERS
| Name |
Description |
Limits |
Required |
| longitude |
Longitude of the location coordinates |
N/A |
Yes |
| latitude |
Latitude of the location coordinates |
N/A |
Yes |
| name |
Address name |
N/A |
No |
| address |
Textual representation of location |
N/A |
No |
Example Request With Location Message
cURL - cURL
curl --location --globoff '{endpoint}api/v2/whatsapp/message/send' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data '{
"channels": [
{
"name": "whatsapp",
"from": "{from}"
}
],
"recipient": {
"to": [
"{receiver}"
]
},
"message" : {
"type": "location",
"payload" : {
"longitude": 12.912985,
"latitude": 77.599505,
"name": "MOBtexting Pvt Ltd",
"address": "JP Nagar, Mini forest"
}
}
}'
Sending Template Message (Highly Structured Message)
Example Request With Template “HSM” (Highly Structured Message)
curl -X POST \
'{endpoint}whatsapp/message/send' \
-H 'authorization: Bearer d9e1cac3812186b353c5022xxxxx' \
-H 'content-type: application/json' \
-d '{
"channels": [{
"name": "whatsapp",
"from": "919019120xxx"
}],
"recipient": {
"to": "91XXXXXX"
},
"message": {
"type": "template",
"payload": {
"name": "otp",
"language": "en",
"components": [{
"type": "header",
"parameters": [{
"type": "text",
"text": "replacement_text"
}]
},
{
"type": "body",
"parameters": [{
"type": "text",
"text": "replacement_text"
},
{
"type": "currency",
"currency": {
"fallback_value": "$100.99",
"code": "USD",
"amount_1000": 100990
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "February 25, 1977",
"day_of_week": 5,
"day_of_month": 25,
"year": 1977,
"month": 2,
"hour": 15,
"minute": 33
}
},
{
"...": "..."
}
]
},
{
"type": "button",
"sub_type": "quick_reply",
"index": "0",
"parameters": [{
"type": "payload",
"payload": "aGlzIHRoaXMgaXMgY29vZHNhc2phZHdpcXdlMGZoIGFTIEZISUQgV1FEV0RT"
}]
},
{
"type": "button",
"sub_type": "url",
"index": "1",
"parameters": [{
"type": "text",
"text": "9rwnB8RbYmPF5t2Mn09x4h"
}]
},
{
"type": "button",
"sub_type": "url",
"index": "2",
"parameters": [{
"type": "text",
"text": "ticket.pdf"
}]
}
]
}
}
}'
Example Product Shipment Request With Template
curl -X POST \
'{endpoint}whatsapp/message/send' \
-H 'authorization: Bearer d9e1cac3812186b353c5022xxxxx' \
-H 'content-type: application/json' \
-d '{
"channels": [{
"name": "whatsapp",
"from": "919019120xxx"
}],
"recipient": {
"to": "91XXXXXX"
},
"message": {
"type": "template",
"payload": {
"name": "oculus_shipment_update",
"language": "en",
"components": "components": [{
"type": "header",
"parameters": [{
"type": "image",
"image": {
"link": "link-to-your-image"
}
}]
},
{
"type": "body",
"parameters": [{
"type": "text",
"text": "Anand"
},
{
"type": "text",
"text": "Quest"
},
{
"type": "text",
"text": "113-0921387"
},
{
"type": "date_time",
"date_time": {
"fallback_value": "23rd Nov 2019",
"day_of_month": "20",
"year": "2019",
"month": "9"
}
}
]
},
{
"type": "button",
"index": "0",
"sub_type": "url",
"parameters": [{
"type": "text",
"text": "1Z999AA10123456784"
}]
}
]
}
}
}'
