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 text message

• Incoming text message with URL

• Incoming message with image, video, audio, document

• Incoming message with geolocation

• Incoming message with contact & contacts array

• Incoming message with quote

• Incoming message with sticker

• Incoming message-emoji reaction

• Incoming message with group invitation

• Incoming message with product

• Incoming message with poll

• Incoming message with poll update

• Incoming message with order

• Incoming channel admin invite

• 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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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:[phone]\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": "[e-mail]",
      "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:[phone]\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:[phone]\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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "timestamp": 1713795443,
      "source": "mobile",
      "product": {
        "product_id": "7275856165856513",
        "catalog_id": "[e-mail]"
      },
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
        "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": "[e-mail]",
        "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": "[e-mail]",
        "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": [
                "[e-mail]"
              ],
              
              "
            },
            {
              "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": "[e-mail]",
      "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": "[e-mail]",
      "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": "[e-mail]",
      "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