message.receivedmessage.sentmessage.updated
Message object events
Heyy currently sends message object webhooks for the following events:message.received: A new inbound message was received on one of your channels.message.sent: A new outbound message was created and sent from Heyy (by an agent, automation, or API call).message.updated: An existing message changed (most commonly delivery status transitions likesent→delivered→read).
Payload fields
Unique identifier for this webhook payload delivery.
The tenant that triggered this webhook event.
The event type for this webhook payload.
The message object associated with the event.
Show properties
Show properties
Message id.
ISO datetime when the message was created.
ISO datetime when the message was last updated.
Chat id this message belongs to.
Channel id this message belongs to.
Message type.
Who sent the message.
Provenance for the message (where it originated).
Show items
Show items
The source type.
Present when
type is "campaign".Present when
type is "automation".Present when
type is "inbox".Present when
type is "api".Present when
type is "ai_agent".status
"none" | "pending" | "sent" | "delivered" | "read" | "scheduled" | "deleted" | "failed"
required
Message delivery status.
Scheduled send time (ISO datetime) if scheduled; otherwise
null.Message content.
Show properties
Show properties
Text body of the message (if present).
Attachments for the message (if present).
Show items
Show items
Attachment id.
type
"image" | "video" | "document" | "audio" | "location" | "contact" | "button" | "list_section" | "quick_reply" | "comment" | "ai_tool_call" | "referral" | "content_reference"
required
Attachment type discriminator.
Present for media attachments (
image, video, document, audio) when available.Present for
audio attachments; indicates a voice note.Present for
location attachments.Present for
location attachments.Present for
location attachments.Present for
location attachments.Present for
contact attachments.Present for
contact attachments.Present for
contact attachments.Present for
contact attachments.Present for
contact attachments.Present for
contact attachments.Present for
button attachments.Present for
button and list_section attachments.Present for
button attachments when available.Show properties
Show properties
Present for
button attachments and for quick_reply attachments.Present for
list_section attachments.Present for
list_section attachments.Present for
list_section attachments.Present for
list_section attachments.Present for
list_section attachments.Present for
ai_tool_call attachments.Present for
ai_tool_call attachments.Present for
ai_tool_call attachments.Present for
ai_tool_call attachments.Present for
ai_tool_call attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
referral attachments.Present for
content_reference attachments.Present for
content_reference attachments.Present for
content_reference attachments.Optional header text (if present).
Optional footer text (if present).
Optional payload (e.g. interactive response payload) if present.
Whether the message was forwarded.
Present when the message is a reply to another message.
Show properties
Show properties
Replied-to message id.
Vendor message id (if available).
Sender of the replied-to message.
Preview type.
Timestamp of the replied-to message.
Preview text (if applicable).
Errors associated with this message (if any).
Show items
Show items
Machine-readable error key.
Human-readable error message.
Vendor-specific error details (if provided).
Show properties
Show properties
Vendor error code.
Vendor error title.
Vendor error type.
Vendor error message.
Vendor trace id (if present).
Vendor message id (if available).
Message timestamp (ISO datetime).
Vendor-specific details (if available).
Show properties
Show properties
WhatsApp vendor details (if available).
Show properties
Show properties
Whether this message is marked sensitive.
AI generation id (if the message was generated by AI); otherwise
null.The contact handle (identity) used for this chat.
{
"id": "f8a2b1c3-4d5e-4f6a-9b0c-1d2e3f4a5b6c",
"tenantId": "a98d0e1f2-a1b4-4c4d-6e7f-8a9b0c1d2e3f",
"event": "message.received",
"data": {
"id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
"type": "message",
"sender": "inbound",
"sources": [
{
"type": "vendor"
}
],
"status": "delivered",
"scheduledAt": null,
"content": {
"body": "Hello world"
},
"forwarded": false,
"reactions": [],
"errors": [],
"history": [],
"vendorId": "wamid.HBgNOTcyNTQ0Nzc4NzcwFQIAEhgUMzJCNzMyRzU0OTQ2MDdDNUE1RTIA",
"timestamp": "2026-03-13T23:29:34.000Z",
"vendorDetails": null,
"isSensitive": false,
"aiGenerationId": null,
"metadata": {},
"chat": {
"id": "5f3700cd-a5cf-4b2b-be5a-23b013025c11"
},
"handle": {
"id": "1a9559d7-3c53-4cd5-a076-962193b206e9",
"type": "phone_number",
"value": "+12135550123"
},
"contact": {
"id": "259c9fec-c831-41ad-8a43-3fdad389d015",
"firstName": "John",
"lastName": "Doe",
"phoneNumber": "+12135550123",
"email": "john@example.com"
},
"channel": {
"id": "h9dd4c3e-b049-4903-b047-e2717f1e88e3",
"type": "whatsapp",
"name": "Examply"
}
}
}