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/sample01.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.
  • Stickers must be exactly 512x512 pixels.
Language
Click Try It! to start a request and see the response here!