Messaging
This documentation describes how to send messages using the WhatsApp Business API.
Introduction
Content of the JSON message body differs for each type of message. See the official WhatsApp documentation for information regarding the parameters of each type of message you want to send to assemble your request payload.
Send Text Message
POST https://waba-v2.360dialog.io/messages
To send a message, use the request URL and the following body parameters.
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "PHONE_NUMBER",
"type": "text",
"text": {
"body": "Hello, dear customer!"
}
}Request Body
messaging_product*
string
Messaging service used for the request: Use "whatsapp"
text*
object
contains body field
type*
string
type of the message: text
recipient_type*
string
individual
A successful response includes a messages object with an ID for the newly created message.
{
"messaging_product": "whatsapp",
"contacts": [
{
"input": "16505076520",
"wa_id": "16505076520"
}
],
"messages": [
{
"id": "wamid.HBgLMTY1MDUwNzY1MjAVAgARGBI5QTNDQTVCM0Q0Q0Q2RTY3RTcA"
}
]
}Formatting in Text Messages
WhatsApp allows some formatting in messages. To format all or part of a message, use these formatting symbols:
Bold
Asterisk (*)
Your total is *$10.50*.
Italics
Underscore (_)
Welcome to _WhatsApp_!
Strike-through
Tilde (~)
This is ~better~ best!
Code
Three backticks (```)
```print 'Hello World';```
Sending URLs in Text Messages
By default, the mobile WhatsApp application recognizes URLs and makes them clickable. To include a URL preview, include "preview_url": true and make sure the URL begins with http:// or https://. A hostname is required, IP addresses are not matched.
The preview-url should be inside the text object.
Example:
"text": {// the text object
"preview_url": true,
"body": You have to check out this amazing messaging service https://www.whatsapp.com/"
}
The majority of the time when you send a URL, whether with a preview or not, the receiver of the message will see a URL that they can click on.
URL previews are only rendered after one of the following has happened:
If the end user did not initiate the conversation with you - you must use a Template message instead for a free-form message.
Message Templates
Please refer to our documentation on Message Templates, which includes the steps required to get your Templates approved, and the process for creating and deleting them.
We strongly advise uploading media intended to use in template messages and the usage of media ID instead of a URL:
Each WhatsApp Business Account can have up to 250 message templates (how many is determined by your plan). That means 250 message template names, and each of them can have multiple language translations.
For example, a message template called hello_world translated into two languages counts as a single message template in regards to this limit.
The message template name field is limited to 512 characters.
The message template content field is limited to 1024 characters.
There is no limit to the number of parameters allowed in a Message Template.
Bulk Messaging
There are two options to send messages in bulk:
1. Use an Integration Partner
Bulk messaging, sometimes known as group messaging, is deprecated in the native WhatsApp API. But the same functionality is available in many of our Integration Partner Applications.
2. Develop your own solution
Code your own solution to send Template messages to a list of contacts.
Error scenarios
400
Bad Request
Check that you are using the correct data type for Booleans and Strings, and that the JSON-payload is well-formed.
Use an online tool (ex. JSON formatter and validator) to validate the payload if you are not sure.
402
Message failed to send because there were one or more errors related to your payment
This happens when a WhatsApp Business Account is created but no Payment Method is set. If you get this error message - contact our support team.
408
Timeout
Message failed to send because it was pending for too long. If this happens, we recommend that you implement graceful timeout handling and retry.
470
Message failed to send because more than 24 hours have passed since the customer last replied to this number (no open session)
Free-form text messages and media messages will result in a failure callback with error 470 when sent outside of the 24h-window. In other words, if it has been more than 24 hours since you last received a user initiated message - the session is closed and you can no longer use free-form messages. To re-initiate a conversation, you must use a Template Message.
500
structure unavailable: Client could not display the highly structured message (hsm)
The Template was not understood by the WhatsApp consumer client. Check the format.
1000
Failed to generate processed file path
This could occur when the file storage is full and files cannot be stored. If you get this error message - contact our support team.
1000
Image file format (audio/mpeg) is not supported
Make sure that the message type matches the MIME-type of the file (ex. audio files should be sent using "audio", not "image"; audio/mpeg is an unsupported combination).
Another reason could be that the video file doesn't have an audio track: then the error message contains something like video/mp4/h264/NONE where NONE is an indicator that the audio track is missing.
1009
Invalid latitude
The valid range is from -90 to 90.
1014
Request for [...] failed
You have provided a URL that seems to be double URL-encoded and the file cannot be delivered because of that, or the file behind the URL doesn't exist.
2001
Template name does not exist in the translation
Check that you are calling the correct language short code. Example:
"language": {
"policy": "deterministic",
"code": "en"
}Message statuses
Received
The receive 'double check' on messages sent by the customer appears when the callback with the received status reaches the 360dialog Webhook.
The receive 'double check' on messages sent by the business appears when the customer’s WhatsApp app receives the message.
Read
The read double check on messages sent by the customer appears when the message is marked as read by the business.
The read double check on messages sent by the business appears when the customer’s WhatsApp app is open in the message.
How to mark a message as read
Make a POST request to /messages
The message_id used in this API call is the id provided in the Webhook Inbound Notification.
POST /messages
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "MESSAGE_ID"
}'Parameters
messaging_product
Required.
Use whatsapp
message_id
Required.
status
Required.
Updating status to read is applicable only for incoming messages.
Check the API Response
A successful response returns:
null # or { "success" : true }Last updated
Was this helpful?