Send messages

Using this API you can send different types of messages to users. The different types of message objects are described here.

Message object description for different `types` of messages

Text message

{
   "type":"text",
   "text":"Hello user, how are you?"
}

Key	Type	Description	Sample
`text`	string	Required The text message that will be sent to the user.	Hello user, how are you?

Image message

{
   "type":"image",
   "originalUrl":"https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg",
   "previewUrl":"https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg",
   "caption":"Sample image"
}

Key	Type	Description	Sample
`originalUrl`	string	Public URL of the image hosted.	https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg
`previewUrl`	string	Public URL of the thumbnail of the image.	https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg
`caption`	string	Optional Caption of the image	Sample image

File message

{
   "type":"file",
   "url":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf",
   "filename":"Sample file"
}

Key	Type	Description	Sample
`url`	string	Public URL of the file hosted	https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf
filename	string	Name of the file	Sample file

Audio message

{
   "type":"audio",
   "url":"https://www.buildquickbots.com/whatsapp/media/sample/audio/sample02.mp3"
}

Key	Type	Description	Sample
`url`	string	Public URL of the audio file.	https://www.buildquickbots.com/whatsapp/media/sample/audio/sample02.mp3

Video message

{
   "type":"video",
   "url":"https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4"
}

Key	Type	Description	Sample
`url`	string	Public URL of the video file.	https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4
`caption`	string	Optional Caption of the video	Sample caption

Sticker message

{
   "type":"sticker",
   "url":"http://www.buildquickbots.com/whatsapp/stickers/SampleSticker01.webp"
}

Key	Type	Description	Sample
`url`	string	Public URL of the sticker file.	http://www.buildquickbots.com/whatsapp/stickers/SampleSticker01.webp

Interactive - List message

{
   "type":"list",
   "title":"title text",
   "body":"body text",
   "msgid":"list1",
   "globalButtons":[
      {
         "type":"text",
         "title":"Global button"
      }
   ],
   "items":[
      {
         "title":"first Section",
         "subtitle":"first Subtitle",
         "options":[
            {
               "type":"text",
               "title":"section 1 row 1",
               "description":"first row of first section description",
               "postbackText":"section 1 row 1 postback payload"
            },
            {
               "type":"text",
               "title":"section 1 row 2",
               "description":"second row of first section description",
               "postbackText":"section 1 row 2 postback payload"
            },
            {
               "type":"text",
               "title":"section 1 row 3",
               "description":"third row of first section description",
               "postbackText":"section 1 row 3 postback payload"
            }
         ]
      },
      {
         "title":"second section",
         "subtitle":"second Subtitle",
         "options":[
            {
               "type":"text",
               "title":"section 2 row 1",
               "description":"first row of second section description",
               "postbackText":"section 1 row 3 postback payload"
            }
         ]
      }
   ]
}

Key	Type	Description	Note
`title`	string	The title/header text for the list message	Maximum characters: 60. Formatting allows emojis, but not markdown.
`body`	string	The body text for the list message	Maximum characters: 1024 Emojis and markdown are supported. Links are supported.
`msgid`	string	Optional It's a developer-defined message-id for a specific list message. The inbound message-event payload consists of this id when the user replies to a list message. It's a feature provided by our platform, and it helps developers set the context of a reply for use-cases like chatbots.
`globalButtons`	array	See globalButtons array description
`items`	array	See items array description	Up to 10 items supported.

`globalButtons` array description

Key	Type	Description	Note
`type`	string	Only `text` is supported as the title of the Global button	- Must always be `text`
`title`	string	The title of the global button	- It cannot be an empty string and must be unique within the message. - Maximum of 20 characters. - Does not allow emojis or markdown.

`items` array description

Key	Type	Description	Note
`title`	string	The title of a section in the list message.	Maximum characters: 24
`options`	array	Contains list of items in a section. See options array description.

`options` array description

Key	Type	Description	Note
`type`	string	Only text is supported
`title`	string	The title of the item in the list.	Maximum characters: 24
`description`	string	Optional The description of the item in the list.	Maximum characters: 72
`postbackText`	string	Optional A custom payload you can configure to receive when the user selects a particular item in the list.

Interactive - Quick reply message

{
   "type":"quick_reply",
   "msgid":"qr1",
   "content":{
      "type":"text",
      "header":"this is the header",
      "text":"this is the body",
      "caption":"this is the footer"
   },
   "options":[
      {
         "type":"text",
         "title":"First",
         "postbackText": "dev-defined-postback1"
      },
      {
         "type":"text",
         "title":"Second",
         "postbackText": "dev-defined-postback2"
      },
      {
         "type":"text",
         "title":"Third",
         "postbackText": "dev-defined-postback3"
      }
   ]
}

{
   "type":"quick_reply",
   "msgid":"qr1",
   "content":{
      "type":"image",
      "url":"https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg",
      "text":"this is the body",
      "caption":"this is the footer"
   },
   "options":[
      {
         "type":"text",
         "title":"First",
         "postbackText": "dev-defined-postback1"
      },
      {
         "type":"text",
         "title":"Second",
         "postbackText": "dev-defined-postback2"
      },
      {
         "type":"text",
         "title":"Third",
         "postbackText": "dev-defined-postback3"
      }
   ]
}

{
   "type":"quick_reply",
   "msgid":"qr1",
   "content":{
      "type":"video",
      "url":"https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4",
      "text":"this is the body",
      "caption":"Sample video"
   },
   "options":[
      {
         "type":"text",
         "title":"First",
         "postbackText": "dev-defined-postback1"
      },
      {
         "type":"text",
         "title":"Second",
         "postbackText": "dev-defined-postback2"
      },
      {
         "type":"text",
         "title":"Third",
         "postbackText": "dev-defined-postback3"
      }
   ]
}

{
   "type":"quick_reply",
   "msgid":"qr1",
   "content":{
      "type":"file",
      "url":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf",
      "text":"this is the body",
      "filename":"Sample file",
      "caption":"this is the footer"
   },
   "options":[
      {
         "type":"text",
         "title":"First",
         "postbackText": "dev-defined-postback1"
      },
      {
         "type":"text",
         "title":"Second",
         "postbackText": "dev-defined-postback2"
      },
      {
         "type":"text",
         "title":"Third",
         "postbackText": "dev-defined-postback3"
      }
   ]
}

Key	Type	Description	Note
`msgid`	string	Optional It's a developer-defined message-id for a specific list message. The inbound message-event payload consists of this id when the user replies to a list message. It's a feature provided by our platform, and it helps developers set the context of a reply for use-cases like chatbots.
`content`	array	See content array description
`options`	array	See options array description	Up to 3 options are supported.

`content` array description

Key	Type	Description	Note
`type`	string	The type of quick reply message.	Supported types: `text`, `image`, `video`, and `document`.
`header`	string	Optional It is header of the text message.	`Header` is only applicable to a quick reply message of type `text`. Maximum characters: 20
`url`	string	Public URL of the media file.	`url` is only applicable to quick reply messages of type: `image`, `video`, and `file`.
`text`	string	It is the body of the message.
`filename`	string	Name of the file.	`filename` is only applicable to a quick reply message of type: `file`.
`caption`	string	Optional It is the footer of the message.	Maximum characters: 60

`options` array description

Key	Type	Description	Note
`type`	string	The type of the button.	Only text type is supported.
`title`	string	The title of the button.	It cannot be an empty string and it must be unique within the message. Maximum characters: 20. Does not allow emojis or markdown.
`postbackText`	string	Developer-defined payload that will be returned when the button is clicked in addition to the display text on the button.

Key

Type

Description

Note

type

string

The type of the button.

Only text type is supported.

title

string

The title of the button.

It cannot be an empty string and it must be unique within the message.

Maximum characters: 20. Does not allow emojis or markdown.

postbackText

string

Developer-defined payload that will be returned when the button is clicked in addition to the display text on the button.

Location message

{
   "type":"location",
   "longitude":72.877655,
   "latitude":19.075983,
   "name":"Mumbai",
   "address":"Mumbai, Maharashtra"
}

Contact message

{
   "type":"contact",
   "contact":{
      "addresses":[
         {
            "city":"Menlo Park",
            "country":"United States",
            "countryCode":"us",
            "state":"CA",
            "street":"1 Hacker Way",
            "type":"HOME",
            "zip":"94025"
         },
         {
            "city":"Menlo Park",
            "country":"United States",
            "countryCode":"us",
            "state":"CA",
            "street":"200 Jefferson Dr",
            "type":"WORK",
            "zip":"94025"
         }
      ],
      "birthday":"1995-08-18",
      "emails":[
         {
            "email":"[email protected]",
            "type":"Personal"
         },
         {
            "email":"[email protected]",
            "type":"Work"
         }
      ],
      "name":{
         "firstName":"John",
         "formattedName":"John Wick",
         "lastName":"Wick"
      },
      "org":{
         "company":"Guspshup",
         "department":"Product",
         "title":"Manager"
      },
      "phones":[
         {
            "phone":"+1 (940) 555-1234",
            "type":"HOME"
         },
         {
            "phone":"+1 (650) 555-1234",
            "type":"WORK",
            "wa_id":"16505551234"
         }
      ],
      "urls":[
         {
            "url":"https://www.gupshup.io",
            "type":"WORK"
         }
      ]
   }
}

Supported Content-Types

Type	Supported Content-Types	Size limit	Note
text	Text content for the message.	Maximum characters supported: 4096.	- To include a URL preview in the message make sure the URL begins with http:// or https://. - For a URL to be previewed, the hostname is required, IP addresses are not considered. - If a text message has multiple URLs, only the first URL is previewed.
image	`image/jpeg`, and `image/png`	Maximum file size: 5 MB	WhatsApp vertically crops images with the 1:91:1 aspect ratio: 800×418 pixels. To communicate effectively, design the image such that the crux information is at the center of the image.
file	Any valid MIME-type	Maximum file size: 100 MB
audio	`audio/aac`, `audio/mp4`, `audio/amr`, `audio/mpeg`, `audio/ogg; codecs=opus`.	Maximum file size: 16 MB	The base audio/ogg type is not supported.
video	`video/mp4`, `video/3gpp`	Maximum file size: 16 MB	Only H.264 video codec and AAC audio codec is supported.
sticker	`.webp`	Maximum file size: 100 KB	- Each sticker has a transparent background. - Stickers must be exactly 512x512 pixels.

Message object description for different types of messages

Text message

Image message

File message

Audio message

Video message

Sticker message

Interactive - List message

globalButtons array description

items array description

options array description

Interactive - Quick reply message

content array description

options array description

Location message

Contact message

Supported Content-Types

Message object description for different `types` of messages

`globalButtons` array description

`items` array description

`options` array description

`content` array description

`options` array description