Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.heyy.io/llms.txt

Use this file to discover all available pages before exploring further.

The webhook payload object is sent whenever an event triggers that you have subscribed to. Message webhooks re-use the same object. We have not added other events yet, but platform events will likely use a slightly different object structure due to their different nature. The Heyy API currently supports the following webhook event types:
  • message.received
  • message.sent
  • message.updated

​
message.received webhook payload

The message.received event is fired when a new inbound message is received on one of your channels. 
{
  "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",
      "attachments": []
    },
    "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"
    }
  }
}
Use this event to react to new customer messages, for example by:
  • Creating or updating conversations in your own system.
  • Triggering internal workflows.
  • Logging messages for analytics or compliance.

​
message.sent webhook payload

The message.sent event is fired when an outbound message is created and sent from Heyy (for example, by an agent, an automation, or an API call). 
{
  "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"
    }
  }
}
You can use this event to:
  • Mirror outbound messages into your own data store.
  • Keep external CRMs or analytics systems in sync.
  • Track which system or agent generated which outbound messages.

​
message.updated webhook payload

The message.updated event is fired when the delivery status of a message changes (for example, from sent to delivered or read or failed, depending on the channel). 
{
  "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"
    }
  }
}
Typical uses for this event include:
  • Updating message delivery/read status in your own UI.
  • Powering reporting or analytics dashboards.
  • Triggering follow-up automations when a message reaches a specific status.

​
Forward compatibility

As Heyy evolves, we may:
  • Add new webhook event types.
  • Add new fields to existing payloads.
To keep your integration robust:
  • Always ignore unknown fields.
  • Rely on the id and event fields for routing logic.
  • Treat the message object as an extensible resource that can gain additional properties over time.