message.received▾

message.received

A contact sent you a message. This is the event that opens the 24-hour session window.

Fires for every inbound message on any connected number. Receiving one opens or extends the 24-hour customer service window, so this is also your cue that free-form replies are allowed.

EVENTmessage.received
Payload
{
  "id": "evt_01JZQ6F5H7K9M1P3R5T7V9XZBD",
  "object": "event",
  "type": "message.received",
  "created_at": "2026-09-06T09:41:02.114Z",
  "api_version": "2026-09-01",
  "data": {
    "object": "message",
    "id": "msg_01JZQ3F8X2K7N4B6Y0R9M5TCWA",
    "wamid": "wamid.SEJnTTIwMTAwNTU1MDEyM0ZRSUFFUmdT",
    "conversation_id": "conv_01JZQ3F8X0QG7T2S4N8V1PZAKD",
    "from": "+201005550123",
    "to": "+15550100200",
    "direction": "inbound",
    "type": "text",
    "text": { "body": "Is my order ready?" },
    "contact": { "wa_id": "201005550123", "name": "Nadia Haddad" },
    "session_expires_at": "2026-09-07T09:41:02.114Z",
    "created_at": "2026-09-06T09:41:02.000Z"
  }
}

Notable fields

typeenumrequired

Message kind. The matching key holds the payload.

textimagedocumentaudiovideostickerlocationcontactsinteractivebuttonreaction

text.bodystring

Present when type is text.

image.idstring

Media id — call retrieve media for a download URL. Inbound media is never sent inline.

interactive.button_replyobject

{ id, title } when the contact tapped a reply button.

interactive.list_replyobject

{ id, title, description } when they picked a list row.

reactionobject

{ message_id, emoji }. An empty emoji means the reaction was removed.

contextobject

{ wamid } when the message quote-replies another.

session_expires_atstringrequired

When free-form replies stop being allowed.

Media arrives as an id

Inbound images and documents carry only a media id. Fetch the bytes within 30 days — after that Meta expires the object.
PreviousDelete a webhook endpointNextmessage.sent