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
string
required
Unique identifier for this webhook payload delivery.
string
required
The tenant that triggered this webhook event.
"message.received" | "message.sent" | "message.updated"
required
The event type for this webhook payload.
Message
required
The message object associated with the event.
Show properties
Show properties
string
required
Message id.
string
required
ISO datetime when the message was created.
string
required
ISO datetime when the message was last updated.
string
required
Chat id this message belongs to.
string
required
Channel id this message belongs to.
"message"
required
Message type.
"outbound" | "inbound" | "unknown" | "system"
required
Who sent the message.
MessageSource[]
required
Provenance for the message (where it originated).
Show items
Show items
"none" | "pending" | "sent" | "delivered" | "read" | "scheduled" | "deleted" | "failed"
required
Message delivery status.
string | null
required
Scheduled send time (ISO datetime) if scheduled; otherwise
null.object
required
Message content.
Show properties
Show properties
string | null
Text body of the message (if present).
MessageAttachment[]
Attachments for the message (if present).
Show items
Show items
string
required
Attachment id.
"image" | "video" | "document" | "audio" | "location" | "contact" | "button" | "list_section" | "quick_reply" | "comment" | "ai_tool_call" | "referral" | "content_reference"
required
Attachment type discriminator.
File | null
boolean
Present for
audio attachments; indicates a voice note.number | null
Present for
location attachments.number | null
Present for
location attachments.string | null
Present for
location attachments.string | null
Present for
location attachments.object[]
Present for
contact attachments.object[]
Present for
contact attachments.object
Present for
contact attachments.object
Present for
contact attachments.object[]
Present for
contact attachments.object[]
Present for
contact attachments."quick_reply" | "url" | "phone_number" | "list_title"
Present for
button attachments.string | null
Present for
button and list_section attachments.object | null
Present for
button attachments when available.string | null
Present for
button attachments and for quick_reply attachments.string | null
Present for
list_section attachments.object[]
Present for
list_section attachments.string
Present for
list_section attachments.string
Present for
list_section attachments.string | null
Present for
list_section attachments.string
Present for
ai_tool_call attachments.string
Present for
ai_tool_call attachments.any
Present for
ai_tool_call attachments.any
Present for
ai_tool_call attachments.any
Present for
ai_tool_call attachments."whatsapp"
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments.string
Present for
referral attachments."story"
Present for
content_reference attachments.string
Present for
content_reference attachments.string
Present for
content_reference attachments.string | null
Optional header text (if present).
string | null
Optional footer text (if present).
string
Optional payload (e.g. interactive response payload) if present.
boolean
required
Whether the message was forwarded.
MessagePreview
Present when the message is a reply to another message.
Show properties
Show properties
string
required
Replied-to message id.
string | null
required
Vendor message id (if available).
"outbound" | "inbound" | "unknown" | "system"
required
Sender of the replied-to message.
"text" | "media" | "audio" | "location" | "contact"
required
Preview type.
string
required
Timestamp of the replied-to message.
string | null
required
Preview text (if applicable).
object[]
required
object[]
required
Errors associated with this message (if any).
Show items
Show items
string
required
Machine-readable error key.
string
required
Human-readable error message.
object
Vendor-specific error details (if provided).
Show properties
Show properties
number | null
Vendor error code.
string | null
Vendor error title.
string | null
Vendor error type.
string | null
Vendor error message.
object
string | null
Vendor trace id (if present).
object[]
required
string | null
required
Vendor message id (if available).
string
required
Message timestamp (ISO datetime).
object | null
required
Vendor-specific details (if available).
Show properties
Show properties
object
WhatsApp vendor details (if available).
Show properties
Show properties
object
object | null
required
boolean
required
Whether this message is marked sensitive.
string | null
required
AI generation id (if the message was generated by AI); otherwise
null.object
required
object
required
{
"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"
}
}
}
{
"id": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a",
"tenantId": "a98d0e1f2-a1b4-4c4d-6e7f-8a9b0c1d2e3f",
"event": "message.sent",
"data": {
"id": "e5f6a7b8-c9d0-4e1f-2a3b-4c5d6e7f8a9b",
"type": "message",
"sender": "outbound",
"sources": [
{
"type": "inbox",
"userId": "b8c9d0e1-f2a3-4b4c-5d6e-7f8a9b0c1d2e"
}
],
"status": "pending",
"scheduledAt": null,
"content": {
"body": "Hello world"
},
"forwarded": false,
"reactions": [],
"errors": [],
"history": [],
"vendorId": "2847123456789012345",
"timestamp": "2026-03-13T23:15:25.166Z",
"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"
}
}
}
{
"id": "c9d0e1f2-a3b4-4c5d-6e7f-8a9b0c1d2e3f",
"tenantId": "a98d0e1f2-a1b4-4c4d-6e7f-8a9b0c1d2e3f",
"event": "message.updated",
"data": {
"id": "d0e1f2a3-b4c5-4d6e-7f8a-9b0c1d2e3f4a",
"type": "message",
"sender": "outbound",
"sources": [
{
"type": "inbox",
"userId": "a3b4c5d6-e7f8-4a9b-0c1d-2e3f4a5b6c7d"
}
],
"status": "delivered",
"scheduledAt": null,
"content": {
"body": "Hello world"
},
"forwarded": false,
"reactions": [],
"errors": [],
"history": [
{
"event": "status_update",
"newStatus": "pending",
"timestamp": "2026-03-13T23:26:57.275Z"
},
{
"event": "status_update",
"newStatus": "sent",
"timestamp": "2026-03-13T23:26:58.000Z"
},
{
"event": "status_update",
"newStatus": "delivered",
"timestamp": "2026-03-13T23:26:58.000Z"
}
],
"vendorId": "a1f2e3d4-c5b6-4a97-8e8f-0d1c2b3a4e5f",
"timestamp": "2026-03-13T23:26:57.275Z",
"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"
}
}
}