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:

  1. Text message
  2. Text message with a URL
  3. Message template
  4. Media message

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.