Messages

/v1/messages

Use the messages node to send text messages, media/documents, Message Templates, and group messages to your customers.

This document covers:

Prerequisites
Requests
Responses
Example

Prerequisites

To use the WhatsApp Business API, you must first authenticate yourself and receive a token that enables you to access the service. See the Login and Authentication documentation for more information on how to do this.
Before your business can message to a number, it must ensure the phone number belongs to a WhatsApp account and get the WhatsApp user ID. See the Contacts documentation for more information on how to do this.
Message must meet the cut-off control service requirements

Request

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:

POST /v1/messages
{
  "recipient_type": "individual" | "group",
  "to": "whatsapp-id" | "whatsapp-group-id",
  "type": "audio" | "contact" | "document" | "hsm" | "image" | "location" | "text",
  
  "audio": {
      "id": "your-media-id",
  }
  
  "document": {
      "id": "your-media-id",
      "caption": "your-document-caption-to-be-sent",
      "filename": "your-document-filename"
  }
  
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-document-caption"
    }
  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-video-caption"
    }
  }

  "text": {
      "body": "your-message-content"
  }
}

The above sample shows different objects such as audio, document, and text for illustration purposes only. A valid request body contains only one of them.

Response

The response includes a combination of following components: meta, messages (payload), and errors. See the API Responses documentation for more information.

The following shows an example of payload in a response; the meta and error objects are omitted for brevity.

{
  "messages": [{ 
    "id": "message-id" 
  }]    
}

If the request is successful, you will receive a response with a message ID. If the request returns an errors section, check the originating message and correct the errors before resending the request.

For more information about errors, see:

Example

When a message is sent in a request, the customer will receive a message such as this:

Received Messages

This image displays messages of the following types, from top to bottom:

Cut-off Control

Cut-off control prevents messages from being delivered to users out of certain conditions. Here's a summary of the requirements:

Regular text messages or media messages (i.e., any non-Template Messages) can only be delivered on the 24 hours after last time customer sent a message to your business.
Template Messages do not have this restriction and should be the preferred way of reaching a customer.
Business account should be eligible for payments

If a message does not meet any of these requirements an error code is sent. Please find more about error codes here.