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?"
}
KeyTypeDescriptionSample
textstringRequired
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"
}
KeyTypeDescriptionSample
originalUrlstringPublic URL of the image hosted.https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg
previewUrlstringPublic URL of the thumbnail of the image.https://www.buildquickbots.com/whatsapp/media/sample/jpg/sample01.jpg
captionstringOptional
Caption of the image
Sample image

File message

{
   "type":"file",
   "url":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf",
   "filename":"Sample file"
}
KeyTypeDescriptionSample
urlstringPublic URL of the file hostedhttps://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf
filenamestringName of the fileSample file

Audio message

{
   "type":"audio",
   "url":"https://www.buildquickbots.com/whatsapp/media/sample/audio/sample02.mp3"
}
KeyTypeDescriptionSample
urlstringPublic 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"
}
KeyTypeDescriptionSample
urlstringPublic URL of the video file.https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4
captionstringOptional
Caption of the video
Sample caption

Sticker message

{
   "type":"sticker",
   "url":"http://www.buildquickbots.com/whatsapp/stickers/SampleSticker01.webp"
}
KeyTypeDescriptionSample
urlstringPublic 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"
            }
         ]
      }
   ]
}
KeyTypeDescriptionNote
titlestringThe title/header text for the list message- Maximum characters: 60.
- Formatting allows emojis, but not markdown.
bodystringThe body text for the list message- Maximum characters: 1024
- Emojis and markdown are supported. Links are supported.
msgidstringOptional
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.
globalButtonsarraySee globalButtons array description
itemsarraySee items array descriptionUp to 10 items supported.
globalButtons array description
KeyTypeDescriptionNote
typestringOnly text is supported as the title of the Global button- Must always be text
titlestringThe 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
KeyTypeDescriptionNote
titlestringThe title of a section in the list message.Maximum characters: 24
optionsarrayContains list of items in a section.
See options array description.
options array description
KeyTypeDescriptionNote
typestringOnly text is supported
titlestringThe title of the item in the list.Maximum characters: 24
descriptionstringOptional
The description of the item in the list.
Maximum characters: 72
postbackTextstringOptional
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"
      }
   ]
}
KeyTypeDescriptionNote
msgidstringOptional
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.
contentobjectSee content object description
optionsarraySee options array descriptionUp to 3 options are supported.
content object description
KeyTypeDescriptionNote
typestringThe type of quick reply message.Supported types: text, image, video, and document.
headerstringOptional
It is header of the text message.
Header is only applicable to a quick reply message of type text.

Maximum characters: 20
urlstringPublic URL of the media file.url is only applicable to quick reply messages of type: image, video, and file.
textstringIt is the body of the message.
filenamestringName of the file.filename is only applicable to a quick reply message of type: file.
captionstringOptional
It is the footer of the message.
Maximum characters: 60
options array description
KeyTypeDescriptionNote
typestringThe type of the button.Only text type is supported.
titlestringThe 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.
postbackTextstringDeveloper-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

TypeSupported Content-TypesSize limitNote
textText 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.
imageimage/jpeg, and image/pngMaximum file size: 5 MBWhatsApp 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.
fileAny valid MIME-typeMaximum file size: 100 MB
audioaudio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus.Maximum file size: 16 MBThe base audio/ogg type is not supported.
videovideo/mp4, video/3gppMaximum file size: 16 MBOnly H.264 video codec and AAC audio codec is supported.
sticker.webpMaximum 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.
Language
Click Try It! to start a request and see the response here!