# message.received

A customer's message was stored

Sent for every message a customer writes to one of your numbers. Use it to answer customers or to keep your own record of the chat. `data` is the [Message](/reference/api/messages/#object).

In the app: Message received. Plan feature `webhooks.messages`. To subscribe over the API: `messages:read`.

## data

- `id` (string, uuid)
- `contact_id` (string, uuid)
- `number_id` (nullable string, uuid): The number it was sent from or to. `null` if that number was removed.
- `direction` (string): One of `incoming`, `outgoing`.
- `type` (string): The kind of message: `text`, `image`, `video`, `audio`, `document`, `sticker`, `template`, `interactive`, `button_reply`, `list_reply`, `flow_reply`, `location`, `contact`, `reaction` or `unsupported`. More values may be added.
- `status` (string): `pending` (accepted, not yet with WhatsApp), `sent`, `delivered`, `read` or `failed` for outgoing messages; `received` for incoming ones.
- `text` (nullable object): The text. For location, contact, reaction, reply and flow messages it's a readable summary.
  - `body` (string)
- `media` (nullable object): The file the message carries, or a template's header file.
  - `url` (string): Where to download it, `/v1/messages/{id}/media`.
  - `mime_type` (nullable string)
  - `filename` (nullable string)
  - `caption` (nullable string)
- `template` (nullable object): The template it was sent with.
  - `id` (nullable string, uuid)
  - `name` (string)
  - `language` (nullable string)
- `interactive` (nullable object): Reply buttons or a link button the message offered.
  - `type` (string): One of `buttons`, `cta_url`.
  - `body` (string)
  - `buttons` (array of objects)
    - `id` (string): 1 to 256 characters.
    - `title` (string): 1 to 20 characters.
  - `url` (nullable string)
  - `display_text` (nullable string)
- `reply_to_message_id` (nullable string, uuid): The message it quotes.
- `whatsapp_message_id` (nullable string): WhatsApp's ID for the message, once WhatsApp has it.
- `error` (nullable object): Why the message failed.
  - `code` (integer): WhatsApp's error code, or 0 if it isn't known.
  - `message` (string)
- `sent_by` (nullable object): Who sent an outgoing message. `null` for incoming ones.
  - `type` (string): Who or what it was: a team member, an API key, the chatbot, the AI, an automation, a broadcast, the WhatsApp Business app or Soosh itself. More values may be added. One of `user`, `api_key`, `bot`, `ai`, `automation`, `broadcast`, `whatsapp_app`, `system`.
  - `id` (nullable string, uuid): The person, key or broadcast. `null` for actors without one, such as the chatbot.
  - `name` (string)
- `broadcast_id` (nullable string, uuid): The broadcast that sent it.
- `created_at` (string, date-time)
- `updated_at` (string, date-time)

## Example event

```json
{
  "id": "evt_2f0ad0d0c17e74f703b3258ad60c5379",
  "type": "message.received",
  "api_version": "2026-10-14",
  "created_at": "2026-10-14T09:12:40.331Z",
  "workspace_id": "2b7e4c1a-9d3f-4a85-b6e2-5f0c8d1a7e34",
  "data": {
    "id": "6a1c3e5b-7d9f-4b2a-8c4e-0f2a4c6e8b1d",
    "contact_id": "4ea0d485-435d-407f-837a-c7d67095f23a",
    "number_id": "0f6d3c1e-5b7a-4c52-9a55-3f6a2d5c8b10",
    "direction": "incoming",
    "type": "text",
    "status": "received",
    "text": {
      "body": "Hi, when will my order arrive?"
    },
    "media": null,
    "template": null,
    "interactive": null,
    "reply_to_message_id": null,
    "whatsapp_message_id": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAEhgUM0E5QjJDNEU2MDFGMjdEOEI1NjUA",
    "error": null,
    "sent_by": null,
    "broadcast_id": null,
    "created_at": "2026-10-14T09:12:40.117Z",
    "updated_at": "2026-10-14T09:12:40.117Z"
  }
}
```