Receiving Events
message.received
A message was observed on the account; data.message.direction identifies inbound or outbound.
Payload by message type
Text
{
"id": "evt_2f9c1a4b7e",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:34:56Z",
"data": {
"conversation": { "id": "8613912345678", "type": "user" },
"sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "wamid.HBgM",
"text": "Hi - is my order shipped yet?",
"direction": "inbound",
"sent_at": "2026-06-08T12:34:55Z"
},
"event": { "kind": "message_received" }
}
}Image (with caption)
{
"id": "evt_4a1c7b9e2f",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:35:02Z",
"data": {
"conversation": { "id": "8613912345678", "type": "user" },
"sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "wamid.HBgN",
"text": "Here's the unboxing photo",
"direction": "inbound",
"sent_at": "2026-06-08T12:35:02Z",
"attachments": [
{
"type": "image",
"url": "https://unifyport-media.oss-cn-hongkong.aliyuncs.com/pro/1/whatsapp/10001/2a1f.jpg?Expires=1749384902&Signature=...",
"mimetype": "image/jpeg"
}
]
},
"event": { "kind": "message_received" }
}
}Voice / Audio
{
"id": "evt_6b2d8c0f3a",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:35:20Z",
"data": {
"conversation": { "id": "8613912345678", "type": "user" },
"sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "wamid.HBgO",
"direction": "inbound",
"sent_at": "2026-06-08T12:35:20Z",
"attachments": [
{
"type": "audio",
"url": "https://unifyport-media.oss-cn-hongkong.aliyuncs.com/pro/1/whatsapp/10001/9c3e.ogg?Expires=1749384920&Signature=...",
"mimetype": "audio/ogg; codecs=opus",
"duration_ms": 8000
}
]
},
"event": { "kind": "message_received" }
}
}Document (large file — url omitted)
{
"id": "evt_7c3e9d1a4b",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:35:45Z",
"data": {
"conversation": { "id": "8613912345678", "type": "user" },
"sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "wamid.HBgP",
"direction": "inbound",
"sent_at": "2026-06-08T12:35:45Z",
"attachments": [
{
"type": "document",
"mimetype": "application/pdf",
"title": "invoice-A1234.pdf",
"metadata": { "is_big_file": true, "size": 87421133 }
}
]
},
"event": { "kind": "message_received" }
}
}Location
{
"id": "evt_8d4f0e2b5c",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:36:10Z",
"data": {
"conversation": { "id": "8613912345678", "type": "user" },
"sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "wamid.HBgQ",
"text": "Shibuya Scramble Square, 2-24-12 Shibuya, Tokyo",
"direction": "inbound",
"sent_at": "2026-06-08T12:36:10Z",
"location": {
"longitude": 139.7020,
"latitude": 35.6580
}
},
"event": { "kind": "message_received" }
}
}Mentioned quoted reply
{
"id": "evt_9e5a1f3c6d",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:36:30Z",
"data": {
"conversation": { "id": "120363041234567890@g.us", "type": "group" },
"sender": { "id": "8613912345678@lid", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "CURRENT-MESSAGE-ID",
"text": "@Alex I am replying to the earlier update.",
"direction": "inbound",
"sent_at": "2026-06-08T12:36:29Z",
"reply_token": "<opaque handle for replying to CURRENT-MESSAGE-ID>",
"reply_to_message_id": "PARENT-MESSAGE-ID",
"mentions": [
{ "id": "8613900001111@lid" }
]
},
"event": { "kind": "message_received" }
}
}Album item
{
"id": "evt_a0f6b2d4e7",
"type": "message.received",
"provider": "whatsapp",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:36:45Z",
"data": {
"conversation": { "id": "8613912345678", "type": "user" },
"sender": { "id": "8613912345678", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "ALBUM-CHILD-MESSAGE-2",
"direction": "inbound",
"sent_at": "2026-06-08T12:36:45Z",
"album": { "id": "ALBUM-PARENT-ID", "index": 2, "total": 3 },
"attachments": [
{
"type": "image",
"url": "https://unifyport-media.oss-cn-hongkong.aliyuncs.com/pro/1/whatsapp/10001/album-2.jpg?Expires=1749385000&Signature=...",
"mimetype": "image/jpeg"
}
]
},
"event": { "kind": "message_received" }
}
}Contact (Telegram)
{
"id": "evt_b1a7c3e5f8",
"type": "message.received",
"provider": "telegram",
"account_id": "acc_8c21d0",
"occurred_at": "2026-06-08T12:37:00Z",
"data": {
"conversation": { "id": "5005", "type": "user" },
"sender": { "id": "4004", "type": "user", "name": "Jordan Lee" },
"message": {
"id": "3003",
"direction": "inbound",
"sent_at": "2026-06-08T12:37:00Z",
"contact": {
"phone_number": "+8600000000000",
"first_name": "Demo",
"last_name": "User",
"vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:Demo User\nEND:VCARD",
"user_id": 4004
}
},
"event": { "kind": "message_received" }
}
}Notes
- data.conversation is the chat, data.sender is who sent it, and data.message holds the public content fields — id, text, direction, sent_at, and optional structured content. reply_to_message_id identifies the parent message, while reply_token is an opaque handle for replying to the current WhatsApp message; never substitute one for the other. Telegram adds conversation.title, sender.username, and an account block; field availability varies by provider.
- data.message.type is an internal normalization field and is not included in the customer webhook payload. Media messages expose their type through data.message.attachments[].type; video and audio add duration_ms, document adds the file title, and oversized files set attachments[].metadata.is_big_file with the url omitted. Structured content uses contact, location {longitude, latitude}, mentions [{id}], or album {id, index, total?}. An album child keeps its own message.id as the idempotency key.