Events Reference

Watzy emits two event types on your registered webhook endpoints.

---

message.received

Fired when a WhatsApp user sends a message to one of your connected phone numbers.

Payload

{
  "event": "message.received",
  "timestamp": "2024-06-06T14:30:00+00:00",
  "data": {
    "account_id": 1,
    "from": "201234567890",
    "message_id": "wamid.HBgLMjAxMjM0NTY3ODkVAgASGCA...",
    "type": "text",
    "body": "Hi, I'd like to track my order.",
    "media_id": null,
    "timestamp": "1717681800"
  }
}

Data fields

Field	Type	Description
account_id	integer	Your Watzy account ID the message arrived on
from	string	Sender's phone number (no + prefix)
message_id	string	WhatsApp message ID
type	string	Message type — see table below
body	string	Text content or a label for media messages
media_id	string | null	Meta media ID (present for image/video/audio/document)
timestamp	string	Unix timestamp from WhatsApp

Message types

type	body value	media_id
text	The text the user typed	null
image	Caption or [Image]	Media ID
video	Caption or [Video]	Media ID
audio	[Audio]	Media ID
document	Caption or [Document]	Media ID
sticker	[Sticker]	Media ID
button	The button text the user tapped	null
(other)	[<type> message]	null

---

message.status_update

Fired when a message you sent has a delivery status change.

Payload

{
  "event": "message.status_update",
  "timestamp": "2024-06-06T14:31:05+00:00",
  "data": {
    "message_id": "wamid.HBgLMjAxMjM0NTY3ODkVAgARGCA...",
    "status": "delivered",
    "errors": [],
    "timestamp": "1717681865"
  }
}

Data fields

Field	Type	Description
message_id	string	The WAMID returned by the send endpoint
status	string	Current status — see table below
errors	array	Non-empty when status is failed
timestamp	string	Unix timestamp from WhatsApp

Status progression

Statuses follow this precedence (highest wins — a message will never downgrade):

sent → delivered → read

A message can also end in failed if Meta could not deliver it.

Status	Meaning
sent	Accepted by Meta, en route to the device
delivered	Arrived on the recipient's device
read	Recipient opened the message
failed	Delivery failed — check errors for the reason

Error object (when status is failed)

{
  "errors": [
    {
      "code": 131047,
      "message": "Re-engagement message: message failed to send because more than 24 hours have passed since the customer last replied."
    }
  ]
}

---

ping

Sent when you click Test on a webhook endpoint in the dashboard. Use it to confirm your server is reachable and responding correctly.

{
  "event": "ping",
  "timestamp": "2024-06-06T14:00:00+00:00",
  "data": {
    "message": "Webhook test from Watzy"
  }
}