Messages

/v1/messages

Use the messages node to send text messages, media/documents, and message templates to your customers.

See the following documentation for information regarding the specfic types of messages you can send:

Before You Start

You will need:

Authenticate yourself and receive a authentication token that enables you to access the service
See the Login and Authentication documentation for more information on how to do this.
To verify the WhatApp account you wish to message and get its WhatsApp user ID
See the Contacts documentation for more information on how to do this.
Meet the cut-off control service requirements for messages

Sending Messages

Message API calls are sent to the /messages node regardless of message type, but the content of the JSON message body differs for each type of message (text, image, etc.).

Request

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio" | "contact" | "document" | "hsm" | "image" | "location" | "text" | "video",
  
  "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 WhatsApp Business API Responses 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 in certain conditions.

Requirements:

Regular text messages or media messages (i.e., any non-message templates) can only be delivered in the 24 hours after last time customer sent a message to your business.
Message templates 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.