Messaging
This documentation describes how to start sending messages to your users.

Introduction

Message API calls are sent to the /messages endpoint regardless of message type, but the content of the JSON message body differs for each type of message (text, image, etc.). See the following documentation for information regarding the type of messages you want to send:
Check out the Best practices on how to approach customers.

Check contacts and send messages

Before sending a message, make sure you meet the prerequisites and use the /v1/contacts endpoint for each number. Otherwise, you may receive a 1006 "Resource not found - unknown contact" error.
Before sending a message to a number, you must check the contact availability. With this procedure, you validate the number and verify the user's identity on WhatsApp. You can find more information about this process in the official Documentation.
post
https://waba.360dialog.io
/v1/contacts
Check Contacts Endpoint

Example Request:

1
POST https://waba.360dialog.io/v1/contacts
2
{
3
"blocking": "wait",
4
"contacts": [
5
"+55123456789"
6
],
7
"force_check": true
8
}
9
‚Äč
Copied!

Example Response:

1
{
2
"contacts": [
3
{
4
"input": "+55123456789",
5
"status": "valid",
6
"wa_id": "55123456789"
7
}
8
],
9
"meta": {
10
"api_status": "stable",
11
"version": "2.35.4"
12
}
13
}
Copied!
The response will contain a wa_id. Use this wa_id when sending messages using the below request.
post
https://waba.360dialog.io
/v1/messages
Send Message

Example Request:

1
{
2
"recipient_type": "individual",
3
"to": "wa_id",
4
"type": "text",
5
"text": {
6
"body": "Hello, dear customer!"
7
}
8
}
Copied!
If the end user did not initiate the conversation with you - you must use a Template message instead. The process is described below.
post
https://waba.360dialog.io
/v1/messages
Send Template Message

Example Request Body

1
{
2
"to": "wa_id",
3
"type": "template",
4
"template": {
5
"namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
6
"language": {
7
"policy": "deterministic",
8
"code": "en"
9
},
10
"name": "template_name"
11
}
12
}
Copied!
‚Äč

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.
    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.
360dialog stores media files for 14 days after upload. Media files older than 14 days may be deleted by 360dialog without prior notice.

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.
Booleans don't need double quotes!
    408: Message failed to send because it was pending for too long There are no further details provided by WhatsApp. The recommendation is to resend the message.
    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. Please find a way to restrict message sending if there was no incoming message for the given user/phone number within 24h. Alternatively, you can contact the user using a Template Message.
    1000: Failed to generate processed file path This could occur when the file storage is full and files cannot be stored. Please reach out to Help and Support.
    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.
    1006 - Unknown contact You did not use the v1/contacts endpoint to get a valid wa_id before sending the message. See the above guide on how to use the v1/contacts endpoint.
    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 The template needs to be set up by our Support team.
    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.

Message statuses

Receive double check

The receive double check on messages sent by the customer appears when the callback with the received status reaches 360dialog Webhook and then notifies the WABA. This setting needs to be set up previously for this to work.
The receive double check on messages sent by the business appears when the customer’s WhatsApp app receives the message.

Read double check

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.
Last modified 26d ago