Messages

/v1/messages

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

See the following guides for information regarding the specfic types of messages you can send: Text Messages, Media Messages, Message Templates, and Other Message Types.

Before You Start

You 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.

Before sending a message, you should also send an API call to the contacts node. The information from checking contacts is cached in the container and not doing this might result in an Unkown Contact error.

Constraints

• The following types of message are supported: text, message templates, images, documents and audio.
• A text message can be a max of 4096 characters long.

Creating

You send messages by making a POST call to the /messages node regardless of message type. The content of the JSON message body differs for each type of message (text, image, etc.).

Parameters

The following parameters are common to all message POST API requests:

"statuses": [
    {
        "errors": [
            {
                "code": 410,
                "title": "Message expired"
            }
        ],
        "id": "gBGGFmkiWVVPAgmurVK0Oo_-o60",
        "recipient_id": "16695551234",
        "status": "failed",
        "timestamp": "1538520126"
    }
]

Text Messages

The following parameters are specific to messages of the text type:

Formatting in Text Messages

WhatsApp allows some formatting in messages. To format all or part of a message, use these formatting symbols:

Media Messages

The following parameters are specific of the following message types: audio, document, image, sticker, and video.

The media Object

Contact Messages

The following parameters are specific to messages of the contact type:

The addresses Object

The emails Object

The name Object

*At least one of the optional parameters needs to be included along with the formatted_name parameter.

The org Object

The phone Object

The urls object

Location Messages

The following parameters are specific to messages of the location type:

Message Templates

The following objects are specific to message templates: template, components, and hsm —The hsm object is planned to be deprecated in a future version of the API.

Inside template, the language object is nested.

Inside components, the parameters object is nested. Additionally, you can set type to button.

The template object

The components object

This object is nested inside the template object.

The parameters object

This object is nested inside the components object.

The button type

Inside the components object, you can set type to button. These are the button parameters:

The hsm Object

The language object

The language parameter sets the language policy for a message template. This field can be nested inside the hsm and template objects.

Example

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

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 response to your call 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 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 WhatsApp Business API Client Error Codes and HTTP Status Codes.

When a message is successfully sent in a request, the customer receives 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.

FAQ

Learn more

• Login and Authentication documentation
• Contacts documentation
• WhatsApp Business API Responses
• WhatsApp Business API Client Error Codes
• HTTP Status Codes