WhatsApp Cloud Message Types

Here are the list of supported message types that can be sent with WhatsApp Cloud:

Text
Image
Audio
Video
Sticker
File
Location
Contact
Reaction
Interactive Message
WhatsApp Message Template

Text

WhatsApp Text Message

{
  "type": "TEXT",
  "text": "Hello World!",
}

Property	Description	Required
type	TEXT	Y
text	String; Limited to 2000 characters	Y

Image

WhatsApp Image

{
  "type": "IMAGE",
  "text": "I am Sanuker!",
  "attachment_id": "289832336612941",
}

Property	Description	Required
type	IMAGE	Y
text	String; caption for image	N
attachment_id	Media ID of the image	Y (or url)
url	URL of the image	Y (or attachment_id)

tip

Image must be a valid image file format: .jpeg or .png
Image must be 8-bit, RGB or RGBA
Maximum file size is 5MB

Audio

WhatsApp Audio Message

{
  "type": "AUDIO",
  "attachment_id": "668795277867495"
}

Property	Description	Required
type	AUDIO	Y
attachment_id	Media ID of the audio	Y (or url)
url	URL of the audio	Y (or attachment_id)

tip

Audio must be a valid audio file format, including .aac, mp4, mpeg, amr, ogg (only opus codecs, base ogg is not supported)
Maximum file size is 16MB

Video

WhatsApp Video

{
  "type": "VIDEO",
  "attachment_id": "496729438556614",
  "text": "TEXT"
}

Property	Description	Required
type	VIDEO	Y
text	String; caption for Video	N
attachment_id	Media ID of the video	Y (or url)
url	URL of the video	Y (or attachment_id)

tip

Video must be a valid video file format, including mp4 and 3gp.
Maximum file size is 16MB.
Only support the H.264 video codec and AAC audio codec.
Support video with a single audio stream or no audio stream

Sticker

WhatsApp Sticker

{
  "type": "STICKER",
  "attachment_id": "1030335650902052"
}

Property	Description	Required
type	VIDEO	Y
url	URL of the sticker	Y (or attachment_id)
attachment_id	Media ID of the sticker	Y (or url)

tip

Image format must be in webp and 512x512 px in dimension
Maximum file size for static sticker: 100KB
Maximum file size for animated sticker : 500KB

File

WhatsApp File

{
  "type": "FILE",
  "filename": "TEXT",
  "attachment_id": "496729438556614"
}

Property	Description	Required
type	FILE	Y
filename	String; preview name of the file	N
url	URL of the file	Y (or attachment_id)
attachment_id	Media ID of the file	Y (or url)

tip

File must be a valid file format, including plain, pdf, vnd.ms-powerpoint, msword1, vnd.ms-excel, vnd.openxmlformats-officedocument.wordprocessingml.document, vnd.openxmlformats-officedocument.presentationml.presentation, vnd.openxmlformats-officedocument.spreadsheetml.sheet.
Maximum file size is 100MB

Location

WhatsApp Location

{
  "type": "LOCATION",
  "location": {
    "name": "ABC Company",
    "address": "Room C, 1/F, DFG Building, 101 Rainbow Road",
    "lat": "22.31586918460027",
    "long": "114.20883121469535"
  }
}

Property	Description	Required
type	LOCATION	Y
name	String; Name of location	N
address	String; Address of Location	N
lat	Latitude	Y
long	Longitude	Y

Contact

{
  "type": "CONTACTS",
  "contacts": [
    {
      "id": "YXpJfusT",
      "name": {
        "formatted_name": "John Lee",
        "first_name": "John",
        "last_name": "Lee",
        "prefix": "Mr"
      },
      "addresses": [
        {
          "type": "work",
          "city": "Hong Kong",
          "street": "Rainbow Road 131, ABC Building"
        }
      ],
      "emails": [
        {
          "type": "work",
          "email": "workmail123@gmail.com"
        }
      ],
      "phones": [
        {
         "type": "main",
         "phone": "+1 413-252-1446",
         "wa_id": "14132521446"
        }
      ],
      "urls": [
        {
          "type": "work",
          "url": "www.sanuker.com"
        }
      ],
      "org": {
        "company": " Sanuker"
      }
    }
  ]
}

Property	Description	Required
name	String; name of contact	Y
address	String; contact address	N
birthday	String; date	N
emails	String; email address	N
org	String; company name	N
phones	String; phone number	N
urls	String; url	N

NOTE

Inside the phones object, the phone and wa_id must be filled so that WhatsApp can recognize it as a valid business account to contact.

Otherwise, only the "Invite to WhatsApp" text will be displayed.

"phones": [
  {
    "type": "main",
    "phone": "+1 413-252-1446",
    "wa_id": "14132521446"
  }
]

Each object in Contact contains one or multiple optional parameters, you can refer to here for details.

Reaction

WhatsApp Reaction

{
  "type": "REACTION",
  "message_id": "wamid.HBgLODUyNTQwNjM1OTgVAgASGBQzRUIwOTVERkZCRDIwODg5REQwMAA=",
  "emoji": "😊"
},

Property	Description	Required?
type	REACTION	Y
message_id	The ID for identifying the message to be reacted to	Y
emoji	The emoji used as reaction; the input can be emoji itself or in Escaped Unicode i.e. `\uD83D\uDE0A`	Y

NOTE

The message ID of a previous message can be obtained from the message event in logs or by using the ApiScope.chat in Open API.

For example:

query chat {
    apiViewer{
        conversationHistory (first: 10, platform: "whatsapp-cloud", memberId: "999abe6524f9db0009963008") {
            edges{
                node{
                    memberId
                    messageEvent
                }
            }
        }
    }
}

Interactive Messages

Interactive Messages allow the users to response quickly by providing buttons to click on. Users cannot select more than one option at the same time from a list or button message, but they can go back and re-open a previous message.

List Messages

List Message - 1

List Message - 2

{
  "type": "WHATSAPP_LIST",
  "header": {
    "type": "text",
    "text": "Hello 👋🏻"
  },
  "body": {
    "text": "Sanuker provides chatbot solutions."
  },
  "footer": {
    "text": "Facebook and WhatsApp Official Business Partner"
  },
  "action": {
    "button": "Menu",
    "sections": [
      {
        "title": "section title",
        "rows": [
          {
            "payload": "GREETINGS",
            "title": "Main Menu",
            "description": "Hello!"
          },
          {
            "payload": "ABOUT_SANUKER",
            "title": "About Sanuker",
            "description": "Who are you?"
          }
        ]
      }
    ]
  }
}

Property	Description	Required?
Header	The header of your list message, only `text` is allowed for list message	N
Body	The body content of the message (Maximum of 1024 characters)	Y
Footer	The footer content (Maximum of 60 characters)	N
Action	Inside action, you must nest: - a button field with your button’s content, and - at least one section object (maximum of 10) Inside section, you must add at least one rows object	Y

action Object

Property	Description	Required?
button	Button content. It cannot be an empty string and must be unique within the message (Maximum of 20 characters)	Y
sections	Array of section objects. There is a minimum of 1 and maximum of 10	Y

section Object

Property	Description	Required?
title	Title of the section	Y (if the message has more than one section.)
rows	Contains a list of rows. Each row must have a title and an ID. You can add a description, but it is optional	Y

Reply Buttons

Reply Button

{
  "type": "WHATSAPP_REPLY_BUTTONS",
  "header": {
    "type": "image",
    "image": {
      "id": "2e5a7aad-e8c7-43ba-ad5e-b298bb32f8af"
    }
  },
  "body": {
    "text": "Sanuker provides chatbot solutions."
  },
  "footer": {
    "text": "Facebook and WhatsApp Official Business Partner"
  },
  "action": {
    "buttons": [
      {
        "type": "reply",
        "reply": {
          "payload": "GREETINGS",
          "title": "Main Menu"
        }
      },
      {
        "type": "reply",
        "reply": {
          "payload": "ABOUT_SANUKER",
          "title": "About Sanuker"
        }
      }
    ]
  }
}

Property	Description	Required
Header	The header of your list message; It can be a text or media: "Image", "Video", "Document"	N
Body	The body content of the message (Maximum of 1024 characters)	Y
Footer	The footer content (Maximum of 60 characters)	N
Action	You must add at least one button, and include type and title.You cannot add more than 3 buttons	Y

action Object

Property	Description	Required?
buttons	A button can contain the following parameters: type: only supported type is reply (for Reply Button Messages) title: Button title. It cannot be an empty string and must be unique within the message (Maximum of 20 characters)	Y

Single Product Message

{
  "type": "PRODUCT",
  "action": {
    "type": "single",
    "catalog_id": "1134377510532066",
    "product_retailer_id": "03-Pack"
  },
  "body": {
    "text": "Check out our Bag of the Day"
  }
}

Property	Description	Required
body	The body content of the message (Maximum of 1024 characters)	N
footer	The footer content (Maximum of 60 characters)	N
action	Must contain - Must be `single` for single-product message. - `catalogId`: an ID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager. - `productId`: a product’s unique identifier (Content ID).	Y

Multi Product Message

tip

Multi-Product Message can only contain a selection of up to 30 products from the inventory.

{
  "type": "PRODUCT",
  "header": {
    "type": "text",
    "text": "Fall Collection"
  },
  "action": {
    "type": "multi",
    "catalog_id": "1134377510532066",
    "sections": [
      {
        "title": "Urban Essentials",
        "product_items": [
          "01-Pack",
          "02-Bag"
        ]
      },
      {
        "title": "Hiking Essentials",
        "product_items": [
          "03-Pack"
        ]
      }
    ]
  },
  "body": {
    "text": "Click view items to see our Fall Collection"
 }
}

Property	Description	Required
header	`type` must be `text`. Contain a text object with the desired content	Y
body	The footer content (Maximum of 1024 characters)	Y
footer	The footer content (Maximum of 60 characters)	N
action	Must contain - `type`: Must be `multi` for multi-product message. - `catalogId`: an ID for the catalog you want to use for this message. Retrieve this ID via Commerce Manager - `sections`: Array of section objects. You must include at least one section	Y

sections field:

Property	Description	Required
title	a title for each section	Y
product_items	`product_retailer_id`: product’s unique identifier (Content ID)	Y

WhatsApp Message Template

WhatsApp Template Message

{
  "type": "TEMPLATE",
  "components": [
    {
      "parameters": [
        {
          "image": {
            "id": "57ec1287-6915-4a44-8dc9-9caa620385e1"
          },
          "type": "image"
        }
      ],
      "type": "header"
    },
    {
      "type": "button",
      "sub_type": "quick_reply",
      "index": "0",
      "parameters": [
        {
          "type": "payload",
          "payload": "Contact Sanuker"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "quick_reply",
      "index": "1",
      "parameters": [
        {
          "type": "payload",
          "payload": "GREETINGS"
        }
      ]
    },
    {
      "type": "button",
      "sub_type": "quick_reply",
      "index": "2",
      "parameters": [
        {
          "type": "payload",
          "payload": "ABOUT_SANUKER"
        }
      ]
    }
  ],
  "languagePolicy": "deterministic",
  "languageCode": "en",
  "namespace": "bc3ac5dd_6dfd_2345_d5f7_123456789bf",
  "elementName": "multiple_button_test_1",
  "accountId": "1234567890"
}

Template Details

Property	Description	Required?
Name	Can only contain lowercase alphanumeric characters and underscores ( _ ); No other characters or white space are allowed	Y
Category	Select the correct category of your template; See list of supported categories	Y
Language	Select the correct language of your template; The template name will be the same for all translations; You will specify the language field when sending out the template; See list of supported languages	Y
Content	The content of your message template; Support parameter placeholders in the format of `{{1}}`	Y
Header	The header of your message template; It can be a text or media: "Image", "Video", "Document"	N
Body	The body of your message template (Character Limit: 1024)	Y
Footer	The text footer of your message template	N
Buttons	The button(s) of your message template; Call-to-action or Quick Reply; 3 buttons max.	N

Maximum Character Limit

Property	Character Limit
Body (Without Header/Footer)	Up to 1024 characters
Body (With Header/Footer)	Up to 160 characters
Header	60 characters
Footer	60 characters

Please tip that, within a WhatsApp Message Template, the character limit does not apply to the varaiable.

Setup Procedure

Open "Response Builder" and choose the response type "WhatsApp Message Template".

Create a WhatsApp Message Template Response

Choose any existing "Message Template". Please make sure your have completed the Message Template Submission process in order to view your existing message templates.
Set the Language Policy as Deterministic.
Choose the Language of your Message Template.

Please see the optional settings below:

Add payload if your Message Template has a Quick Reply button.

Add Payload Buttons to WhatsApp Message Template

Add Media ID or url if your Header has multimedia files like image or video.

Add Media to WhatsApp Message Template

Reply to

You can send message as a reply to a previous message in the conversation. The previous message will be quoted in the contextual bubble and be displayed together with the replying message.

While sending any messages to WhatsApp user, you need to add the property reply_to and identify the contextual message with the Message ID

{
  "type": "TEXT",
  "text": "Hello there! How is it going?",
  "reply_to": "wamid.HBgLODUyNTQwNjM1OTgVAgASGBQzRUIwQjBGOTBBREU1QTgzQkRFQwA="
}

Property	Description	Required
reply_to	Message ID of the message to be replied to	Y

NOTES

Only messages that are 30 days old or less can be quoted in the contextual bubble. Otherwise, the message will be sent normally instead of as a reply.
Recipients will not see the contextual bubble if the replying message is a message template.
Recipients on KaiOS will not see the contextual bubble if the replying message is an image, video, audio or PTT.
The message ID of a previous message can be obtained from the message event in logs or by using the ApiScope.chat in Open API.

For example:

query chat {
    apiViewer{
        conversationHistory (first: 10, platform: "whatsapp-cloud", memberId: "999abe6524f9db0009963008") {
            edges{
                node{
                    memberId
                    messageEvent
                }
            }
        }
    }
}

Text​

Image​

tip

Audio​

tip

Video​

tip

Sticker​

tip

File​

tip

Location​

Contact​

NOTE

Reaction​

NOTE

Interactive Messages​

List Messages​

Reply Buttons​

Single Product Message​

Multi Product Message​

tip

WhatsApp Message Template​

Template Details​

Maximum Character Limit​

Setup Procedure​

Reply to​

NOTES

Text

Image

Audio

Video

Sticker

File

Location

Contact

Reaction

Interactive Messages

List Messages

Reply Buttons

Single Product Message

Multi Product Message

WhatsApp Message Template

Template Details

Maximum Character Limit

Setup Procedure

Reply to