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 specific 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 an 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 Unknown 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

These are the main parameters used in /messages POST API requests:

The text Object

The media Object

For the On-Premises API, the media object id is returned when the media is successfully uploaded to the WhatsApp Business API client via the media endpoint.

The contacts Object

Inside contacts, you can nest the following objects: addresses, emails, name, org, phone, and urls.

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

The location Object

The template object

Inside template, you can nest the components and the language objects.

Beginning with v2.27.8, a template's namespace must be the namespace associated with the WhatsApp business account that owns the phone number associated with the current WhatsApp Business API client or the message fails to send.

The components object

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

The parameters object

The button type

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

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.

The On-Premises API used to have fallback as a language policy option. That was deprecated with v2.27.8.

The hsm Object

The interactive Object

The interactive object generally contains 4 main components: header, body, footer, and action. Additionally, some of those components can contain one or more different objects:

• Inside header, you can nest media objects.
• Inside action, you can nest section and button objects.

The header Object

The body Object

The footer Object

The action Object

The section Object

"rows": [
  {
   "id":"unique-row-identifier-here",
   "title": "row-title-content-here",
   "description": "row-description-content-here",           
   }
]

The product Object

Examples

Audio messages:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "audio",
  "audio": {
      "id": "your-media-id",
  }
}

Document messages, using filename:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "id": "your-media-id",
      "caption": "your-document-caption-to-be-sent",
      "filename": "your-document-filename"
  }
}

Document messages, using link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "document",
  "document": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-document-caption"
    }
}

Video messages, using link:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "video",
  
  "video": {
      "link": "http(s)://the-url"
      "provider": {
          "name" : "provider-name"
      }
      "caption": "your-video-caption"
    }
  }
}

Text messages:

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "text": {
      "body": "your-message-content"
  }
}

Interactive messages (lists):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "interactive":{
    "type": "list",
    "header": {
      "type": "text",
      "text": "your-header-content-here"
    },
    "body": {
      "text": "your-text-message-content-here"
    },
    "footer": {
      "text": "your-footer-content-here"
    },
    "action": {
      "button": "cta-button-content-here",
      "sections":[
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        {
          "title":"your-section-title-content-here",
          "rows": [
            {
              "id":"unique-row-identifier-here",
              "title": "row-title-content-here",
              "description": "row-description-content-here",           
            }
          ]
        },
        ...
      ]
    }
  }

}

Interactive messages (reply buttons):

POST /v1/messages
{
  "recipient_type": "individual",
  "to": "whatsapp-id",
  "type": "text",
  "interactive": {
    "type": "button",
    "header": { # optional
      "type": "text" | "image" | "video" | "document",
      "text": "your text"
      # OR
      "document": {
        "id": "your-media-id",
        "filename": "some-file-name"
      }
      # OR
      "document": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name",
        },
        "filename": "some-file-name"
      },
      # OR
      "video": {
        "id": "your-media-id"
      }
      # OR
      "video": {
        "link": "the-provider-name/protocol://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
      # OR
      "image": {
        "id": "your-media-id"
      }
      # OR
      "image": {
        "link": "http(s)://the-url",
        "provider": {
          "name": "provider-name"
        }
      }
    }, # end header
    "body": {
      "text": "your-text-body-content"
    },
    "footer": { # optional
      "text": "your-text-footer-content"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "First Button’s Title" 
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "unique-postback-id",
            "title": "Second Button’s Title" 
          }
        }
      ] 
    } # end action   
  } # end interactive

}

Interactive messages (Multi and Single Product Messages):

{ 
  "recipient_type": "individual",
  "to" : "{{Recipient-WA-ID}}",
  "type": "interactive",
  "interactive": {
    "type": "product",
    "body": {
      "text": "body text"
    },
    "footer": {
      "text": "footer text"
    },
    "action": {
      "catalog_id": "catalog-ID",
      "product_retailer_id": "product-ID"
    }
  }
}

Interactive messages (Multi-Product Messages):

{ 
  "recipient_type": "individual",
  "to" : "whatsapp-id",
  "type": "interactive",
  "interactive": 
    {
    "type": "product_list",
    "Header":{
       "type": "text",
        "text": "text-header-content"
     },
     "body":{
        "text": "text-body-content"
      },
     "footer":{
        "text":"text-footer-content"
     },
     "action":{
        "catalog_id":"catalog-id",
        "sections": [
             {
             "title": "section-title",             
             "product_items": [
                  { "product_retailer_id": "product-SKU-in-catalog" },
                  { "product_retailer_id": "product-SKU-in-catalog" },
                            ...
              ]},
              {
              "title": "the-section-title",
              "product_items": [
                 { "product_retailer_id": "product-SKU-in-catalog" }
                           ...
              ]},
               ...
       ]
     },  
    }
}

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.

Formatting in Text Messages

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

Performance

In this context, performance represents the number of messages that can be sent in any given second using the WhatsApp Business API client. The maximum achievable performance depends on a variety of factors, the most important factor being your client setup choice and whether a message is being sent to a new user or an existing user —encryption sessions setup take a little longer when messaging a new user.

FAQ

Learn more

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