message.received
A customer wrote.
Fires when a customer's message is saved to a conversation on any channel — WhatsApp (Cloud and QR), Telegram, Messenger, Instagram or the web widget — whoever is handling the conversation at the time. Once per message: a provider delivering the same message twice raises it once. Media arrives with its type (image, audio, document…) and any caption as text.
Does not fire for anything the business sends: the assistant's replies, a flow's messages, your team's replies from the inbox, and the owner's replies from the WhatsApp Business app on a coexistence number. Not for the history WhatsApp imports when a coexistence number is connected. Not for delivery or read receipts.
Header Parameters
t=<unix seconds>,v1=<hex HMAC-SHA256 of "{t}.{body}">, with a second v1 while a rotated secret still signs. Verify it before trusting the body.
The event's type, so a receiver can route before parsing.
This delivery's id. A resend of the same event keeps the envelope id and gets a new delivery id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Every event arrives in this envelope. Fields are only ever added, and a field that can be empty is sent as null rather than left out. Deduplicate on id: a delivery can arrive more than once.
Response Body
Example Requests
/message.received