> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs-parschat.parstechai.com/api-reference/webhook-events/message-webhook/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs-parschat.parstechai.com/_mcp/server.

# message

POST 

A message was sent or received, **including attachments**. There is no separate attachment event: a file arrives as a `message` with a non-text `type` and the file in `attachments`.

The envelope is identical on every channel. What differs is inside `data`: Instagram carries a `source` and an Instagram `sender`, Telegram carries a Telegram user id and no `source`, and an AI or operator reply carries `sender: null`.

`data.external_id` is your idempotency key. Attachment URLs are time-limited, so download the file when the event arrives rather than storing the URL.

Reference: https://docs-parschat.parstechai.com/api-reference/webhook-events/message-webhook

## Request

### Payload

- `schema_version` (string, optional) — Semver for the payload shape. Fields are added without a major bump; nothing is removed or repurposed without one.
- `event` (string, optional) — Which event this is.
- `delivery_id` (string, optional) — Unique per delivery attempt. Log it, and use it to detect a redelivery.
- `occurred_at` (datetime, optional) — When the event happened.
- `robot_id` (string, optional) — The robot it belongs to.
- `external_id` (string, optional) — Your own id for that robot, echoed on every event so you never need a lookup table.
- `channel_id` (string, optional) — The channel it arrived on.
- `data` (WebhooksMessageWebhookPayloadContentApplicationJsonSchemaData, optional) — The message.

## Types

### WebhooksMessageWebhookPayloadContentApplicationJsonSchemaData

The message.

- `conversation_id` (string, optional) — The conversation it belongs to.
- `message_id` (string, optional) — ParsChat id for the message.
- `external_id` (string, optional, nullable) — Your idempotency key. `null` on messages we originated.
- `source` (enum, optional) — Instagram only. The entry point that produced it. Absent on other channels.
  - Allowed values: `direct`, `comment`, `story_reply`, `story_mention`, `reel`
- `media_id` (string, optional, nullable) — Present only when the event originated from a post or reel.
- `role` (enum, optional) — Who sent it.
  - Allowed values: `client`, `operator`, `ai`, `system`
- `type` (enum, optional) — What it carries.
  - Allowed values: `text`, `voice`, `image`, `video`, `multimedia`, `document`, `poll`, `form`, `template`
- `text` (string, optional, nullable) — Plain body. Empty or null on a file-only message.
- `markdown_content` (string, optional, nullable) — Rich rendering when the content has formatting. `text` stays plain, so a partner with two surfaces can use both. Either may be null.
- `reply_to_id` (string, optional, nullable) — The `message_id` this replies to.
- `form_data` (list of WebhooksMessageWebhookPayloadContentApplicationJsonSchemaDataFormDataItems, optional, nullable) — Present when `type` is `form`. Not Instagram-only: a widget customer sends the same shape.
- `attachments` (list of Attachment, optional) — Files on the message.
- `is_edited` (boolean, optional) — Whether the message was edited after sending.
- `sender` (WebhooksMessageWebhookPayloadContentApplicationJsonSchemaDataSender, optional, nullable) — The end customer. `null` when we sent the message (AI or operator).
- `created_at` (datetime, optional) — When the message was created.

### WebhooksMessageWebhookPayloadContentApplicationJsonSchemaDataFormDataItems

- `type` (string, optional)
- `situation` (string, optional)
- `key` (string, optional)
- `value` (string, optional)

### Attachment

A file on a message.

- `type` (enum, optional) — What kind of file this is.
  - Allowed values: `image`, `video`, `voice`, `document`
- `url` (string, optional) — Where to download it. Time-limited: fetch it when the event arrives.
- `mime` (string, optional) — Media type.
- `filename` (string, optional) — Original filename, when the sender supplied one.
- `size_bytes` (integer, optional) — File size.
- `duration_seconds` (integer, optional) — Length of a voice or video file.

### WebhooksMessageWebhookPayloadContentApplicationJsonSchemaDataSender

The end customer. `null` when we sent the message (AI or operator).

- `id` (string, optional)
- `username` (string, optional)