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.

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. There is no support for sending messages with animated stickers. - 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