Incoming message
This section describes the webhook format for an incoming text message.
You can find more details about all parameters and their types in the WebHook documentation.
Incoming HSM-Template message (WhatsApp Business Account (WABA)
The messages array contains all messages that were sent to the webhook URL. Sent on event "messages.post" or "messages.put". We mentioned more about the events here: Mode setting
Incoming text message
Use the messages.post setting to get this webhook.
{
"messages": [
{
"id": "p.w30M7fgwWD4XwHu.g4CA-gBgTwl0rVw",
"from_me": false,
"type": "text",
"chat_id": "[email protected]",
"timestamp": 1712995245,
"source": "mobile",
"text": {
"body": "Hello world"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Read incoming message
{
"statuses": [
{
"id": "p.w30M7fgwWD4XwHu.g4CA-gBgTwl0rVw",
"code": 4,
"status": "read",
"recipient_id": "[email protected]",
"timestamp": "1712995290"
}
],
"event": {
"type": "statuses",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming reply by button
{
"messages": [
{
"id": "g0jEG0ZsSobn4yNGGU3TAg-gDYOS60TLw",
"from_me": false,
"type": "reply",
"chat_id": "[email protected]",
"timestamp": 1726126124,
"source": "mobile",
"chat_name": "Jonathan Customer",
"reply": {
"type": "buttons_reply",
"buttons_reply": {
"id": "ButtonsV3:randomId1",
"title": "Button1"
}
},
"context": {
"quoted_id": "yqKj.Z7XWg0g1lA-wD8Sij1GoQ",
"quoted_author": "919984351847",
"quoted_content": {
"header": "Header with text",
"body": "Body message",
"footer": "Footer message",
"buttons": [
{
"type": "quick_reply",
"text": "Button1",
"id": "ButtonsV3:randomId1"
},
{
"type": "quick_reply",
"text": "Button2",
"id": "ButtonsV3:randomId2"
}
]
},
"quoted_type": "hsm"
},
"from": "61371989950",
"from_name": "Jonathan"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-PF238"
}Incoming text message with URL
{
"messages": [
{
"id": "wbvJ8Fr71sq2L8lPILge.Q-gLUTwl0rVw",
"from_me": false,
"type": "link_preview",
"chat_id": "[email protected]",
"timestamp": 1713201613,
"source": "mobile",
"link_preview": {
"body": "This is text with url https://whapi.cloud/features",
"url": "https://whapi.cloud/features",
"title": "Enriched Cloud API for WhatsApp - Our Features",
"id": "file-c1bbc9f05afbd6cab62fc94f20b81ef9-80b513c25d2b57",
"sha256": "ckBXLlYx8dYz2Qe9ZGWNbzxFH6T+mYrElsVyOOIQd28=",
"description": "Our API allowing you to connect your website or system to your WhatsApp account, send messages to your customers, and efficiently manage your groups, contacts, orders, goods etc.",
"preview": "data:image/jpeg;base64,/9j/4AAQSkZ........."
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with document
The link parameter will only appear when the Auto Download setting is enabled, which downloads files to the cloud and stores them for 30 days.
{
"messages": [
{
"id": "tGZmYoiXecvbKahzwpwKmg-gEcTwl0rVw",
"from_me": false,
"type": "document",
"chat_id": "[email protected]",
"timestamp": 1713201784,
"source": "mobile",
"document": {
"id": "pdf-b487668896662779cbdb29a3c29c0a9a-804713c25d2b57",
"mime_type": "application/pdf",
"file_size": 1438781,
"sha256": "TdxdgX8lBzV6/SYW96F/BEh19ob0eFAn4wKAWhWpUyk=",
"file_name": "File_example.pdf",
"link": "https://s3.eu-central-1.wasabisys.com/in-files/61371989950/pdf-b487668896662779cbdb29a3c29c0a9a-804713c25d2b57.pdf",
"caption": "This is text with file",
"filename": "File_example.pdf",
"page_count": 14,
"preview": "data:image/jpeg;base64,/9j/4AAQSkZJ.........."
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with voice audio
The link parameter will only appear when the Auto Download setting is enabled, which downloads files to the cloud and stores them for 30 days.
{
"messages": [
{
"id": "oOv4asxjzsG949lluzApPg-gFETwl0rVw",
"from_me": false,
"type": "voice",
"chat_id": "[email protected]",
"timestamp": 1713206474,
"source": "mobile",
"voice": {
"id": "oga-a0ebf86acc6d9653cec1bde3bb30293e-805113c25d2b57",
"mime_type": "audio/ogg; codecs=opus",
"file_size": 7848,
"sha256": "BDxh78Oq9X0BDIU4MpWd0tiJCLQVGo6Cr22OisLAXmU=",
"link": "https://s3.eu-central-1.wasabisys.com/in-files/61371989950/oga-a0ebf86acc6d9653cec1bde3bb30293e-805113c25d2b57.oga",
"seconds": 3
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with geolocation
{
"messages": [
{
"id": "d1pxYYXaaoS.ViAtmE6rPA-gAoTwl0rVw",
"from_me": false,
"type": "location",
"chat_id": "[email protected]",
"timestamp": 1713202936,
"source": "mobile",
"location": {
"latitude": 44.5381067,
"longitude": 25.7787495,
"preview": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQA........"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with Live geolocation
{
"messages": [
{
"id": "RdtP4a16Zs._BbcgvC3N6w-gGMTwl0rVw",
"from_me": false,
"type": "live_location",
"chat_id": "[email protected]",
"timestamp": 1713202720,
"source": "mobile",
"live_location": {
"latitude": 44.5381067,
"longitude": 25.7787495,
"caption": "My live location",
"sequence_number": 1713202719671001,
"preview": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQA........."
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with contact
{
"messages": [
{
"id": "sTttJjRHIePJR_WK7JUJgQ-gMkTwl0rVw",
"from_me": false,
"type": "contact",
"chat_id": "[email protected]",
"timestamp": 1713203367,
"source": "mobile",
"contact": {
"name": "Whapi Dev Channel",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Channel;Whapi;Dev;;\nFN:Whapi Dev Channel\nORG:Helloworld College\nTITLE:\nTEL;type=Mobile;waid=61280155346:+61 2 8015 5346\nEND:VCARD"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with contacts array
{
"messages": [
{
"id": "P1.zAHRrD4eWwbkzhJlu5w-gC8Twl0rVw",
"from_me": false,
"type": "contact_list",
"chat_id": "[email protected]",
"timestamp": 1713203412,
"source": "mobile",
"contact_list": {
"list": [
{
"name": "Dev Whapi Checker",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Checker;Dev;Whapi;;\nFN:Dev Whapi Checker\nTEL;type=Mobile:+1 (216) 744-1018\nEND:VCARD"
},
{
"name": "Whapi Dev Channel",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nN:Channel;Whapi;Dev;;\nFN:Whapi Dev Channel\nORG:Helloworld College\nTITLE:\nTEL;type=Mobile;waid=61280155346:+61 2 8015 5346\nEND:VCARD"
}
]
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with quote
{
"messages": [
{
"id": "K5iXSDAPkTxTzMTUBLMvcA-gEATwl0rVw",
"from_me": false,
"type": "text",
"chat_id": "[email protected]",
"timestamp": 1713203447,
"source": "mobile",
"text": {
"body": "Thanks"
},
"context": {
"quoted_id": "yqJRppZk7BI-wNoTwl0rVw",
"quoted_author": "61371989950",
"quoted_content": {
"body": "Hello from API"
},
"quoted_type": "text"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with sticker
The link parameter will only appear when the Auto Download setting is enabled, which downloads files to the cloud and stores them for 30 days.
{
"messages": [
{
"id": "nkiUVCEQLYex741Bm4NqSQ-gIYTwl0rVw",
"from_me": false,
"type": "sticker",
"chat_id": "[email protected]",
"timestamp": 1713203569,
"source": "mobile",
"sticker": {
"id": "webp-9e489d8745421102b1ef8d419b836a49-808613c25d2b57.webp",
"mime_type": "image/webp",
"file_size": 266046,
"sha256": "3Hng4qYEzT/NquSSh/UhbAaIw+cXqhdSjtGaPufYFVM=",
"link": "https://s3.eu-central-1.wasabisys.com/in-files/61371989950/webp-9e489d8745421102b1ef8d419b836a49-808613c25d2b57.webp",
"width": 512,
"height": 512,
"animated": true
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message-emoji reaction
{
"messages": [
{
"id": "BTRGsVX7LoFWE5Bkd0eVAA-gOcTwl0rVw",
"from_me": false,
"type": "action",
"chat_id": "[email protected]",
"timestamp": 1713203716,
"source": "mobile",
"action": {
"target": "yqJRppZk7BI-wNoTwl0rVw",
"type": "reaction",
"emoji": "๐"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with group invitation
{
"messages": [
{
"id": "O5AqBFcFuC_q561s.EcMVg-gJsTwl0rVw",
"from_me": false,
"type": "group_invite",
"chat_id": "[email protected]",
"timestamp": 1713795517,
"source": "mobile",
"group_invite": {
"body": "Hello https://chat.whatsapp.com/BxAwBxLeLKnEkf2wn5EZLK",
"url": "https://chat.whatsapp.com/BxnEkf2xLeLKAwBwn5EZLK",
"title": "Name changed ๐ฅ Yar!",
"invite_code": "BxnEkf2xLeLKAwBwn5EZLK",
"id": "file-3b902a045705b82feae7ad6cf8470c56-813c2509bd2b57",
"sha256": "UocyuqaECIdhfhXFyWviPjlrK1jHVmiYpUowtO8MeHQ=",
"description": "WhatsApp Group Invite",
"preview": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQA.........."
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with product
{
"messages": [
{
"id": "QS5K3_XwtfXnQU9bxJRBPQ-gIQTwl0rVw",
"from_me": false,
"type": "product",
"chat_id": "[email protected]",
"timestamp": 1713795443,
"source": "mobile",
"product": {
"product_id": "7275856165856513",
"catalog_id": "[email protected]"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with catalog
{
"messages": [
{
"id": "yqJGSHAr3x0-gGgTwl0rVw",
"from_me": false,
"type": "catalog",
"chat_id": "[email protected]",
"timestamp": 1713795236,
"source": "mobile",
"catalog": {
"body": "Look at this!\nhttps://wa.me/c/919984351847",
"url": "https://wa.me/c/919984351847",
"canonical": "https://wa.me/c/919984351847",
"title": "MyShop",
"catalog_id": "919984351847",
"preview": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..........."
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with poll
Use the messages.post setting to get this webhook.
{
"messages": [
{
"id": "9N4IF5zS1OwY9m.NUBE3ag-gE8Twl0rVw",
"from_me": false,
"type": "poll",
"chat_id": "[email protected]",
"timestamp": 1713205837,
"source": "mobile",
"poll": {
"title": "My question",
"options": [
"Point 1",
"Point 2",
"Point 3"
],
"total": 0,
"results": [
{
"name": "Point 1",
"voters": [],
"count": 0,
},
{
"name": "Point 2",
"voters": [],
"count": 0,
"id": "PkUcpv6T9mfhcvvYv+/AvR2Viu/lslMGqNBgQA0bDqE="
},
{
"name": "Point 3",
"voters": [],
"count": 0,
"id": "rCoFUNfBRqhGNPoWG0jD4H1vR4PyPqU1rLUdx84Bt64="
}
]
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with poll update
Use the messages.post setting to get this webhook.
{
"messages": [
{
"id": "acvd9A6XTf_nC7q5H3w2Og-wNMTwl0rVw",
"from_me": true,
"type": "action",
"chat_id": "[email protected]",
"timestamp": 1713205922,
"source": "mobile",
"status": "sent",
"action": {
,
"type": "vote",
[
"PkUcpv6T9mfhcvvYv+/AvR2Viu/lslMGqNBgQA0bDqE=",
"rCoFUNfBRqhGNPoWG0jD4H1vR4PyPqU1rLUdx84Bt64="
]
},
919984351847",
"from_name": "Dev Whapi"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}How to Quickly Check the Vote Count in a Poll
To see the final results of a poll, you can use the Get Message endpoint and provide the message ID of the poll. This will return the full voting data.
If you'd like to track the number of votes in real time, enable the messages.patch webhook.
Each time a vote is submitted or updated, you'll receive a webhook event containing:
"total"โ total number of votes"count"โ vote count for each poll option"voters"โ a list of users who voted for each option
This allows you to monitor poll activity as it happens.
Use the messages.patch setting to get this webhook:
{
"messages_updates": [
{
"id": "9N4IF5zS1OwY9m.NUBE3ag-gE8Twl0rVw",
"trigger": {
"id": "acvd9A6XTf_nC7q5H3w2Og-wNMTwl0rVw",
"from_me": false,
"type": "action",
"chat_id": "[email protected]",
"timestamp": 1747730574,
"source": "web",
"device_id": 20,
"chat_name": "Pedro,
"action": {
"target": "9N4IF5zS1OwY9m.NUBE3ag-gE8Twl0rVw",
"type": "vote",
"votes": [
"PkUcpv6T9mfhcvvYv+/AvR2Viu/lslMGqNBgQA0bDqE="
]
},
"from": "919984351847",
"from_name": "Pedro"
},
"before_update": {
"id": "9N4IF5zS1OwY9m.NUBE3ag-gE8Twl0rVw",
"from_me": true,
"type": "poll",
"chat_id": "[email protected]",
"timestamp": 1747730565,
"source": "api",
"device_id": 86,
"status": "read",
"poll": {
"title": "My Poll",
"options": [
"Option 1",
"Option 2"
],
"vote_limit": 1,
"results": [
{
"name": "Option 1",
"voters": [],
"count": 0,
"id": "+uLbCT4d0xBC6KuUJ+hnOnDEP0vFGSNdmiMu+tYHaao="
},
{
"name": "Option 2",
"voters": [],
"count": 0,
"id": "IGsWdw8fem7qt0eGrTwDO+s6oODsSUPzmJD9UoxU5EU="
}
]
},
"from": "84865364571"
},
"after_update": {
"id": "9N4IF5zS1OwY9m.NUBE3ag-gE8Twl0rVw",
"from_me": true,
"type": "poll",
"chat_id": "[email protected]",
"timestamp": 1747730565,
"source": "api",
"device_id": 86,
"status": "read",
"poll": {
"title": "My Poll",
"options": [
"Option 1",
"Option 2"
],
"vote_limit": 1,
"results": [
{
"name": "Option 1",
"voters": [
"[email protected]"
],
"
},
{
"name": "Option 2",
"voters": [],
"id": "IGsWdw8fem7qt0eGrTwDO+s6oODsSUPzmJD9UoxU5EU="
}
]
},
"from": "84865364571"
},
"changes": [
"poll"
]
}
],
"event": {
"type": "messages",
"event": "patch"
},
"channel_id": "MANTIS-M72HC"
}Incoming message with order
{
"messages": [
{
"id": "7GZVXunkHjZaIOgEgWPPrw-gDMTwl0rVw",
"from_me": false,
"type": "order",
"chat_id": "[email protected]",
"timestamp": 1713264543,
"source": "mobile",
"order": {
"order_id": "964278151888836",
"seller": "61371989950",
"title": "Jonathan",
"token": "AR4ToE6jF7HwiKY8cUChFb+h6Blgb0sbRMOY3vwRHhsaeg==",
"item_count": 3,
"currency": "AUD",
"total_price": 359,
"status": "new",
"preview": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQAB......"
},
"from": "919984351847",
"from_name": "Gerald"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Incoming channel admin invite
{
"messages": [
{
"id": "yqLJwDbyoe8-gGcOS60TLw",
"from_me": false,
"type": "admin_invite",
"chat_id": "[email protected]",
"timestamp": 1713863006,
"source": "api",
"device_id": 24,
"admin_invite": {
"newsletter_id": "120363260670839366@newsletter",
"newsletter_name": "My journey",
"expiration": 1714401910,
"body": "Hi buddy, please help me with my channel"
},
"from": "61371989950",
"from_name": "Jonathan"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-PF298"
}Incoming HSM-Template message (WhatsApp Business Account (WABA)
{
"messages": [
{
"id": "D47hovYN9GXp-gJASdDLolQ",
"from_me": false,
"type": "hsm",
"chat_id": "[email protected]",
"timestamp": 1713206231,
"source": "business_api",
"from": "919703374655",
"from_name": "919703374655"
}
],
"event": {
"type": "messages",
"event": "post"
},
"channel_id": "MANTIS-M72HC"
}Format
id*
string
Message ID
type*
MessageType string
default: text
Message type
Enum: [ text, image, video, gif, audio, voice, short, document, link_preview, location, live_location, contact, contact_list, sticker, system, call, unknown, action, group_invite, product, interactive, reply, poll, hsm, order, story ]
subtype
string
Message subtype
chat_id*
string
Chat ID
from
string
WhatsApp ID of the sender
from_me*
boolean
Is message from me
from_name
string
Pushname of the sender
source
MessageSource string
default: text
Message source
Enum: [ web, mobile, api, system, business_api ]
timestamp*
number
Message timestamp
device_id
number
Device ID, if the message was not sent through the app
status
StatusEnum string
List [ "Message failed to send (Red error triangle in WhatsApp Mobile)", "Message pending to send (One clock in WhatsApp Mobile)", "Message received by WhatsApp server (One checkmark in WhatsApp Mobile)", "Message delivered to recipient (Two checkmarks in WhatsApp Mobile)", "Message read by recipient (Two blue checkmarks in WhatsApp Mobile)", "Voice-message played by recipient (Two blue checkmarks in WhatsApp Mobile)", "Message deleted by the user" ]
Message ack status
Enum: [ failed, pending, sent, delivered, read, played, deleted ]
action
Message action {
target
string
Target message ID or chat ID
type*
string
Type of action
Enum: [ edit, delete, reaction, ephemeral, vote ]
emoji
string
Action emoji for reaction
ephemeral
integer
Ephemeral message duration
edited_type
MessageType
edited_content
Message content
votes
[List of poll options
string]
}
context
Message context {
forwarded
boolean
Is forwarding message
forwarding_score
integer($int32)
Count fo forwarding message
mentions
[The numbers of the mentioned users]
quoted_id
string
ID of quoted message
quoted_type
MessageType
quoted_content
Message content
quoted_author
ephemeral
}
reactions
Reactions for message
Last updated
Was this helpful?