Skip to main content

WhatsApp Cloud Message Types

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

Text

WhatsApp Text Message
WhatsApp Text Message
{
"type": "TEXT",
"text": "Hello World!",
}
PropertyDescriptionRequired
typeTEXTY
textString; Limited to 2000 charactersY

Image

WhatsApp Image
WhatsApp Image
WhatsApp Image
WhatsApp Image
{
"type": "IMAGE",
"text": "I am Sanuker!",
"attachment_id": "289832336612941",
}
PropertyDescriptionRequired
typeIMAGEY
textString; caption for imageN
attachment_idMedia ID of the imageY (or url)
urlURL of the imageY (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
WhatsApp Audio Message
{
"type": "AUDIO",
"attachment_id": "668795277867495"
}
PropertyDescriptionRequired
typeAUDIOY
attachment_idMedia ID of the audioY (or url)
urlURL of the audioY (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
WhatsApp Video
WhatsApp Video
WhatsApp Video
{
"type": "VIDEO",
"attachment_id": "496729438556614",
"text": "TEXT"
}
PropertyDescriptionRequired
typeVIDEOY
textString; caption for VideoN
attachment_idMedia ID of the videoY (or url)
urlURL of the videoY (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
WhatsApp Sticker
{
"type": "STICKER",
"attachment_id": "1030335650902052"
}
PropertyDescriptionRequired
typeVIDEOY
urlURL of the stickerY (or attachment_id)
attachment_idMedia ID of the stickerY (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
WhatsApp File
WhatsApp File
WhatsApp File
{
"type": "FILE",
"filename": "TEXT",
"attachment_id": "496729438556614"
}
PropertyDescriptionRequired
typeFILEY
filenameString; preview name of the fileN
urlURL of the fileY (or attachment_id)
attachment_idMedia ID of the fileY (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
WhatsApp Location
{
"type": "LOCATION",
"location": {
"name": "ABC Company",
"address": "Room C, 1/F, DFG Building, 101 Rainbow Road",
"lat": "22.31586918460027",
"long": "114.20883121469535"
}
}
PropertyDescriptionRequired
typeLOCATIONY
nameString; Name of locationN
addressString; Address of LocationN
latLatitudeY
longLongitudeY

Location Request

WhatsApp Location Request
WhatsApp Location Request
{
"type": "LOCATION_REQUEST_MESSAGE",
"action": {
"name": "send_location"
},
"body": {
"text": "Please share you location"
}
}
PropertyDescriptionRequired
typeLOCATION_REQUEST_MESSAGEY
namesend_locationY
textText messageN

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"
}
}
]
}
PropertyDescriptionRequired
nameString; name of contactY
addressString; contact addressN
birthdayString; dateN
emailsString; email addressN
orgString; company nameN
phonesString; phone numberN
urlsString; urlN
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
WhatsApp Reaction
{
"type": "REACTION",
"message_id": "wamid.HBgLODUyNTQwNjM1OTgVAgASGBQzRUIwOTVERkZCRDIwODg5REQwMAA=",
"emoji": "😊"
},
PropertyDescriptionRequired?
typeREACTIONY
message_idThe ID for identifying the message to be reacted toY
emojiThe emoji used as reaction; the input can be emoji itself or in Escaped Unicode i.e. \uD83D\uDE0AY
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 - 1
List Message - 2
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?"
}
]
}
]
}
}
PropertyDescriptionRequired?
HeaderThe header of your list message, only text is allowed for list messageN
BodyThe body content of the message (Maximum of 1024 characters)Y
FooterThe footer content (Maximum of 60 characters)N
ActionInside 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

PropertyDescriptionRequired?
buttonButton content. It cannot be an empty string and must be unique within the message (Maximum of 20 characters)Y
sectionsArray of section objects. There is a minimum of 1 and maximum of 10Y

section Object

PropertyDescriptionRequired?
titleTitle of the sectionY (if the message has more than one section.)
rowsContains a list of rows. Each row must have a title and an ID. You can add a description, but it is optionalY

Reply Buttons

Reply Button
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"
}
}
]
}
}
PropertyDescriptionRequired
HeaderThe header of your list message; It can be a text or media: "Image", "Video", "Document"N
BodyThe body content of the message (Maximum of 1024 characters)Y
FooterThe footer content (Maximum of 60 characters)N
ActionYou must add at least one button, and include type and title.You cannot add more than 3 buttonsY

action Object

PropertyDescriptionRequired?
buttonsA 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"
}
}
PropertyDescriptionRequired
bodyThe body content of the message (Maximum of 1024 characters)N
footerThe footer content (Maximum of 60 characters)N
actionMust 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"
}
}
PropertyDescriptionRequired
headertype must be text. Contain a text object with the desired contentY
bodyThe footer content (Maximum of 1024 characters)Y
footerThe footer content (Maximum of 60 characters)N
actionMust 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:

PropertyDescriptionRequired
titlea title for each sectionY
product_itemsproduct_retailer_id: product’s unique identifier (Content ID)Y

WhatsApp Message Template

WhatsApp Template Message
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

PropertyDescriptionRequired?
NameCan only contain lowercase alphanumeric characters and underscores ( _ ); No other characters or white space are allowedY
CategorySelect the correct category of your template; See list of supported categoriesY
LanguageSelect 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 languagesY
ContentThe content of your message template; Support parameter placeholders in the format of {{1}}Y
HeaderThe header of your message template; It can be a text or media: "Image", "Video", "Document"N
BodyThe body of your message template (Character Limit: 1024)Y
FooterThe text footer of your message templateN
ButtonsThe button(s) of your message template; Call-to-action or Quick Reply; 3 buttons max.N

Maximum Character Limit

PropertyCharacter Limit
Body (Without Header/Footer)Up to 1024 characters
Body (With Header/Footer)Up to 160 characters
Header60 characters
Footer60 characters

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

Setup Procedure

  1. Open "Response Builder" and choose the response type "WhatsApp Message Template".
Create a WhatsApp Message Template Response
Create a WhatsApp Message Template Response
  1. Choose any existing "Message Template". Please make sure your have completed the Message Template Submission process in order to view your existing message templates.

  2. Set the Language Policy as Deterministic.

  3. Choose the Language of your Message Template.

  1. 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 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
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="
}
PropertyDescriptionRequired
reply_toMessage ID of the message to be replied toY
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
}
}
}
}
}