---
title: "Message received"
method: POST
path: "message.received"
---

# Message received

`POST message.received` (webhook)

Incoming webhook deliveries are authenticated with HMAC signature headers (`X-Chatway-Signature` and `X-Chatway-Timestamp`), not your Chatway API key.

A visitor sent a new message.

> Triggered only for visitor messages.

Use message.received to route an incoming question, add it to a transcript, or prepare a reply. Pass `data.conversation.id` as conversation_id to [Create Message](https://developers.chatway.app/operations/messages.store) when replying. Use `data.message.id` to identify the message and the envelope id to detect retries. A message can contain attachments without content, so an absent text field does not mean it is empty. Subscribe to [Message sent](https://developers.chatway.app/webhooks/webhook.message_sent) if your transcript also needs agent replies.

For the complete receive-and-reply flow, see the [Quickstart](https://developers.chatway.app/operations/guides.quickstart).

## Headers

- `X-Chatway-Event` string, required
- `X-Chatway-Webhook-Id` string, uuid, required
- `X-Chatway-Delivery-Id` string, required
- `X-Chatway-Delivery-Attempt` string, required
- `X-Chatway-Timestamp` string, required
- `X-Chatway-Signature` string, required

## Payload

- object
  - `id` string, required: Stable event ID (`evt_…`). Same across HTTP retries for this notification.
  - `event` string, required: Event name. For this webhook, always `message.received`.
  - `data` object, required: Payload for message.received.
    - `message` object, required
      - `id` string, uuid, required: Message ID.
      - `content` string: Message text. May be omitted when attachments are present.
      - `attachments` object[], required: Zero or more attachment objects. Each item has `content` (URL), optional `type`, `mime`, `original_file_name`, and `size` (bytes)—see Webhooks overview → Field reference → Attachment.
        - `content` string, required: Public URL of the file (up to 2048 characters).
        - `type` string: Logical type (for example image, file, video).
        - `mime` string: MIME type when known.
        - `original_file_name` string: Original filename when available.
        - `size` integer, nullable: Size in bytes when known.
      - `created_at` string, date-time, required: When the message was created.
    - `conversation` object, required
      - `id` string, uuid, required: Conversation ID.
      - `channel` string, required: Normalized channel.
      - `status` string, required: Conversation status.
      - `widget_name` string: Present when the conversation is tied to a website widget.
      - `identifier` string: Widget identifier when widget_name is present.
    - `visitor` object, required
      - `id` string, uuid, required: Visitor/contact ID.
      - `name` string: Visitor name. Omitted when empty.
      - `email` string, nullable, required: Visitor email. Always present; null when unknown.
      - `phone` string, nullable, required: Visitor phone. Always present; null when unknown.
  - `occurred_at` string, date-time, required: When the business event occurred.
  - `version` string, required: Payload schema version.

## Acknowledgement `200`

Return any 2xx status to acknowledge receipt.

## Other responses

- `410`: Optional HTTP 410 Gone to signal the endpoint is permanently unavailable. Like every non-2xx response below 500 (including `408` and `429`), it is not retried. It does not disable the subscription; turn the webhook off in Chatway Settings if you want deliveries to stop.

---

[API](https://skmtc.dev/chatway/apis/chatway-developer-docs.md) · [All operations](https://skmtc.dev/chatway/apis/chatway-developer-docs/llms.txt) · [OpenAPI document](https://skmtc.dev/chatway/apis/chatway-developer-docs/revisions/ca1a1da291cc?raw)