# message.received

HTML: https://www.app2email.com/docs/api/webhooks/message.received · Index: https://www.app2email.com/docs/api/llms.txt

A contact sent a message or tapped a button. While WhatsApp's AI agent holds the conversation (owner whatsapp_ai) a reply goes through only after it passes the conversation on (conversation.owner_changed).

Group: Messages. Header `X-App2email-Event: message.received`. Inside the envelope `{id, type, created, number, test?, data}` ([envelope, headers, signature](https://www.app2email.com/docs/api/webhooks.md)). Every webhook of the number gets every number event: filter by `type`.

## data

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `data.message_id` | string | yes |  |
| `data.from` | string | yes |  |
| `data.from_user_id` | string |  | The contact's business-scoped user id, when WhatsApp gave one. |
| `data.media_url` | string |  | app2email's stored copy of received media (GET /v1/{number}/media/{message_id}). |
| `data.name` | string |  |  |
| `data.type` | string | yes | text, image, video, audio, document, sticker, location, contacts, reaction, button, interactive, order, request_welcome (the contact opened the chat), system, unsupported ... |
| `data.text` | string |  |  |
| `data.button` | object |  |  |
| `data.button.text` | string |  |  |
| `data.button.payload` | string |  |  |
| `data.in_reply_to` | string |  |  |
| `data.conversation_url` | string |  |  |
| `data.timestamp` | string |  |  |
| `data.context` | object |  | What it replies to or forwards. |
| `data.context.from` | string |  |  |
| `data.context.id` | string |  |  |
| `data.context.forwarded` | boolean |  |  |
| `data.context.frequently_forwarded` | boolean |  |  |
| `data.context.referred_product` | object |  | any keys |
| `data.referral` | object |  | The ad or post a click-to-WhatsApp message came from.; any keys |
| `data.location` | object |  |  |
| `data.location.latitude` | number |  |  |
| `data.location.longitude` | number |  |  |
| `data.location.name` | string |  |  |
| `data.location.address` | string |  |  |
| `data.location.url` | string |  |  |
| `data.contacts` | object[] |  | Shared contact cards, as Meta sent them. |
| `data.reaction` | object |  |  |
| `data.reaction.message_id` | string |  |  |
| `data.reaction.emoji` | string |  | Empty when the reaction was removed. |
| `data.interactive` | object |  |  |
| `data.interactive.type` | string |  | button_reply, list_reply, nfm_reply ... |
| `data.interactive.id` | string |  |  |
| `data.interactive.title` | string |  |  |
| `data.interactive.description` | string |  |  |
| `data.flow` | object |  | A WhatsApp Flow's answer (interactive nfm_reply). |
| `data.flow.name` | string |  |  |
| `data.flow.body` | string |  |  |
| `data.flow.token` | string |  | The flow_token sent with the Flow. |
| `data.flow.response` | object |  | What the contact filled in.; any keys |
| `data.order` | object |  |  |
| `data.order.catalog_id` | string |  |  |
| `data.order.text` | string |  |  |
| `data.order.product_items` | object[] |  |  |
| `data.identity_key_hash` | string |  | The contact's identity key hash (the identity check is on): send it back as recipient_identity_key_hash. |
| `data.whatsapp` | object |  | Meta's object, unchanged.; any keys |

## Samples

### text

```json
{
  "id": "evt_Xq3k9m2Lw8Rt5Yp1Zs01",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "name": "Sample Contact",
    "type": "text",
    "text": "Hi, is my order on its way?",
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z",
    "from_user_id": "AU.1234567890123456",
    "whatsapp": {
      "from": "61412345678",
      "from_user_id": "AU.1234567890123456",
      "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
      "timestamp": "1762390800",
      "type": "text",
      "text": {
        "body": "Hi, is my order on its way?"
      }
    }
  }
}
```

### image

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs017",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "from_user_id": "AU.1234567890123456",
    "media_url": "https://api.app2email.com/v1/4976659348270/media/wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA%3D",
    "name": "Sample Contact",
    "type": "image",
    "text": "[IMAGE, photo.jpg, image/jpeg, 48213 bytes] Is this the right part?",
    "in_reply_to": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBJPUklHSU5BTF9NRVNTQUdFAA==",
    "context": {
      "from": "4976659348270",
      "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBJPUklHSU5BTF9NRVNTQUdFAA=="
    },
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}
```

### button reply

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs012",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "from_user_id": "AU.1234567890123456",
    "name": "Sample Contact",
    "type": "interactive",
    "text": "Track my order",
    "in_reply_to": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBJPUklHSU5BTF9NRVNTQUdFAA==",
    "interactive": {
      "type": "button_reply",
      "id": "track",
      "title": "Track my order"
    },
    "context": {
      "from": "4976659348270",
      "id": "wamid.HBgLNjE0MTIzNDU2NzgVAgASGBJPUklHSU5BTF9NRVNTQUdFAA=="
    },
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}
```

### location

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs013",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "name": "Sample Contact",
    "type": "location",
    "text": "-33.8688,151.2093 Sydney Opera House",
    "location": {
      "latitude": -33.8688,
      "longitude": 151.2093,
      "name": "Sydney Opera House",
      "address": "Bennelong Point, Sydney NSW 2000"
    },
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}
```

### flow

```json
{
  "id": "evt_Pa3k9m2Lw8Rt5Yp1Zs014",
  "type": "message.received",
  "created": "2026-11-06T01:00:00.000Z",
  "number": "4976659348270",
  "data": {
    "message_id": "wamid.HBgLNjE0MTIzNDU2NzgVAgARGBJTQU1QTEVfVEVTVF9FVkVOVAA=",
    "from": "61412345678",
    "name": "Sample Contact",
    "type": "interactive",
    "text": "Sent",
    "interactive": {
      "type": "nfm_reply"
    },
    "flow": {
      "name": "flow",
      "body": "Sent",
      "token": "booking-1234",
      "response": {
        "date": "2026-11-20",
        "people": "2",
        "flow_token": "booking-1234"
      }
    },
    "conversation_url": "https://www.app2email.com/conversation/61412345678_4976659348270_SAMPLEk3XbQ9rTzP2mW",
    "timestamp": "2026-11-06T01:00:00.000Z"
  }
}
```

Send it to your URL: https://www.app2email.com/docs/api/webhooks/tester?type=message.received
