Event Reference
All outbound webhooks share a common envelope. The data field varies by eventType.
Common envelope
| Field | Type | Description |
|---|---|---|
eventType | string | message, status, order, media.ready, or test |
userId | number | ChatYug tenant user ID |
wabaId | string | WhatsApp Business Account ID |
phoneNumberId | string | Phone number that received or sent the event |
eventId | string | Idempotency key (typically Meta message or status ID) |
occurredAt | string | ISO 8601 UTC timestamp when ChatYug dispatched the event |
data | object | Event-specific payload (see below) |
eventType: message
Fired when a customer sends an inbound message.
{
"eventType": "message",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"occurredAt": "2026-07-13T07:00:00.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"contacts": [
{
"profile": { "name": "Rahul Sharma" },
"wa_id": "919876543210"
}
],
"message": {
"from": "919876543210",
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"timestamp": "1720856400",
"type": "text",
"text": { "body": "Hello, I need help with my order" }
}
}
}The message object follows Meta's inbound message schema. Types include text, image, document, interactive (button/list replies), order, and flow submissions (nfm_reply).
For image / video / audio / document, the Meta payload includes only a media id (not a downloadable URL). Wait for media.ready (below) or call GET /api/external/messages/:chatyugMessageId/media after you discover the ChatYug message ID from the conversations API.
eventType: media.ready
Fired after ChatYug downloads inbound media from Meta and stores it under /received_media/. Use this for a stable HTTPS file URL. The earlier message event is unchanged (Meta-shaped) for backward compatibility.
{
"eventType": "media.ready",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==_media",
"occurredAt": "2026-07-13T07:00:02.000Z",
"data": {
"metaMessageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"chatyugMessageId": "223900",
"mediaType": "image",
"mimeType": "image/jpeg",
"mediaPath": "/received_media/919586753155/image_1720856402000_123456789.jpg",
"mediaUrl": "https://chatyug.com/received_media/919586753155/image_1720856402000_123456789.jpg",
"caption": "Invoice photo"
}
}| Field | Description |
|---|---|
metaMessageId | Same as Meta message.id from the preceding message event |
chatyugMessageId | ChatYug Message_Id (use with GET /api/external/messages/:id/media) |
mediaUrl | Absolute HTTPS URL served by ChatYug (preferred for download) |
mediaPath | Relative path under the ChatYug public root |
Recommended client flow: handle message → if type is media, wait for media.ready matching metaMessageId → fetch data.mediaUrl. Alternatively poll GET /api/external/conversations/:id/messages until mediaPending is false and mediaUrl is an https:// link.
eventType: status
Fired when an outbound message status changes.
{
"eventType": "status",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"occurredAt": "2026-07-13T07:00:05.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"status": {
"id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA==",
"status": "delivered",
"timestamp": "1720856405",
"recipient_id": "919876543210"
}
}
}status.status values include sent, delivered, read, and failed.
eventType: order
Fired when a customer submits a WhatsApp catalog cart order.
{
"eventType": "order",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "100000000000001",
"eventId": "900000000000003",
"occurredAt": "2026-07-13T07:01:00.000Z",
"data": {
"metadata": {
"display_phone_number": "+91 98765 43210",
"phone_number_id": "100000000000001"
},
"contacts": [
{
"profile": { "name": "Rahul Sharma" },
"wa_id": "919876543210"
}
],
"order": {
"catalog_id": "900000000000003",
"product_items": [
{
"product_retailer_id": "SKU-1001",
"quantity": 2,
"item_price": 499,
"currency": "INR"
}
]
}
}
}eventType: test
Sent from Webhook Settings when you click "Send test event".
{
"eventType": "test",
"userId": 42,
"wabaId": "100000000000002",
"phoneNumberId": "test-phone-number-id",
"eventId": "test_1720856400000",
"occurredAt": "2026-07-13T07:00:00.000Z",
"data": {
"message": "Webhook test event from Chatyug portal",
"businessName": "Example Business Pvt Ltd"
}
}