Messaging

This documentation describes how to send messages using the WhatsApp Business API.

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. See the official WhatsApp documentation for information regarding the type of messages you want to send.

Check contacts and send messages

Info

Before sending a message, make sure you meet the messaging prerequisites.

Before sending a message to a number, you may check contact availability alongside preloading contact information before sending a message to the number. We recommend the preloading of contact information before sending messages in large volumes, for improved performance. You can find more information about this process in the official WhatsApp documentation.

Warning

Starting in v2.39 and above, you do not have to call the contacts node before sending a message sending a message.

Starting in v2.43, there will be changes to the behavior of the contacts endpoint.

Responses for status will change.

Regardless of whether a user has WhatsApp, it will always return valid for status in the response and a wa_id. There is no guarantee that the returned wa_id will be valid. These changes are applicable for both direct responses, as well as webhook responses for non-blocking calls Ensure your code avoids relying on status and wa_id returned in the contacts node.

Check Contacts Endpoint

Send an API call to /v1/contacts containing an array of registered phone numbers. The phone numbers can be in any standard telephone number format.

POST {{base-url}}/v1/contacts

ParametersResponse (200)Example RequestExample Response

Name	Description
`blocking` (string)	`no_wait` (default), `wait`
`contacts` (array)	`+4912345678910`
`false_check` (boolen)	`false` (default), `true`

    {
    "contacts": [ {
        "input": "+55123456789",
        "wa_id": "55123456789", 
        "status": "valid" <- we can send messages to valid contacts only
    }]
    }

POST https://{baseUrl}/v1/contacts
{
"blocking": "wait",
"contacts": [
"+55123456789"
],
"force_check": true
}

    {
        "contacts": [
            {
                "input": "+55123456789",
                "status": "valid",
                "wa_id": "55123456789"
            }
        ],
        "meta": {
            "api_status": "stable",
            "version": "2.35.4"
        }
    }

Send Message

To send a message, use the request URL and the following body parameters.

POST {{base-url}}/v1/messages

ParametersResponse (201)Example Request

Name	Description
`recipient_type` (string)	`individual`
`to` (string)	wa_id
`type` (string)	text
`text` (object)	contains body field

    {
        "messages": [
            {
                "id": "gBGHSRUUIXKJTwIJVQgXRR0rdXiv"
            }
        ],
        "meta": {
            "api_status": "stable",
            "version": "2.31.5"
        }
    }

    POST https://{baseUrl}/v1/messages
    {
        "recipient_type": "individual",
        "to": "wa_id",
        "type": "text",
        "text": {
            "body": "Hello, dear customer!"
        }
    }

If the end user did not initiate the conversation with you - you must use a Template message instead for a free-form message.

Warning

For non template messages, sending a message to a phone number without a WhatsApp account will result in a webhook notification related to the messaging attempt containing a 470 error code.

Send Template Message

POST {{base-url}}/v1/messages

ParametersExample 1 - Sending Basic Template Message Example 2 - Sending Media Template Message with Parameters

Name	Description
`to` (string)	recipient wa_id
`type` (string)	message type
`namespace` (string)	template namespace
`langugae` (string)	template language
`policy` (string)	delivery policy
`code` (string)	language code
`name` (string)	template name

POST https://{baseUrl}/v1/messages
    {
        "to": "wa_id",
        "type": "template",
        "template": { 
        "namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
            "language": {
                "policy": "deterministic",
                "code": "en"
            },
            "name": "template_name"
        }
    }

Warning

Ensure your code handles a potential 1013 "User is not valid" error when trying to send a template message, which is returned on sending a template message to a phone number without a WhatsApp account.

    POST https://{baseURL}/v1/messages
{
    "to": "wa_id",
    "type": "template",
    "template": {
        "namespace": "c8ae5f90_307a_ca4c_b8f6_d1e2a2573574",
        "language": {
            "policy": "deterministic",
            "code": "en"
        },
        "name": "template_name",
        "components": [{
                "type": "header",
                "parameters": [{
                        "type": "image",
                        "image": {
                            "link": "https://link-to-your-image.jpg"
                        }
                    }
                ]
            }, {
                "type": "body",
                "parameters": [{
                        "type": "text",
                        "text": "John"
                    }, {
                        "type": "text",
                        "text": "1234abcd"
                    }
                ]
            }
        ]
    }
}

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.

Error scenarios

For a complete overview of API error codes and status messages, please see Official WhatsApp documentation.

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
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.
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"
    }
```
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

Received

The receive 'double check' on messages sent by the customer appears when the callback with the received status reaches the CBOT 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.

To mark a message as read, follow the instructions below:

STEP 1 make PUT request to /messages

The message_id used in this API call is the id provided in the Webhook Inbound Notification.

    PUT /v1/messages/message-id
    {
        "status": "read"
    }