---
title: "Message events"
method: POST
path: "messageEvents"
tags: ["Webhook Events"]
---

# Message events

`POST messageEvents` (webhook)

- `message.received`: A new direct message arrived from another user; only new messages emit it, not history imported when a conversation is first synced.
- `message.sent`: A message was sent through PostZen (dashboard, API, or a comment automation, including its Opening DM, follow-request, and nudge messages as well as the final DM); messages sent from the platform's own app do not emit it.

Delivered as a `POST` to every active endpoint that subscribes to the event and whose profile access covers it. Delivery is at least once and events are not ordered, so deduplicate by `id`.

## Payload

- WebhookMessageEvent: Envelope for `message.received`, `message.sent`.
  - `id` string, required: Event id (`evt_…`). Stable across automatic retries and manual redeliveries; deduplicate on it.
  - `type` 'message.received' | 'message.sent', required
  - `apiVersion` string, required: Payload version.
  - `createdAt` string, date-time, required: When the event was created.
  - `data` WebhookMessageEventData, required
    - `message` WebhookMessageEventMessage, required
      - `id` string, required: Platform message id.
      - `conversationId` string: Platform conversation id, the `conversationId` the inbox endpoints accept. Omitted only for a comment automation's private reply when PostZen has not synced that conversation yet.
      - `accountId` string, required: PostZen account id.
      - `profileId` string, required: The account's profile.
      - `platform` 'x' | 'instagram' | 'tiktok' | 'linkedin' | 'facebook' | 'youtube' | 'threads' | 'pinterest' | 'bluesky' | 'telegram', required: Platform of the account an event refers to. Webhook payloads use `x` for X (Twitter).
      - `direction` 'incoming' | 'outgoing', required: `incoming` for message.received, `outgoing` for message.sent.
      - `text` string: Message text, when present.
      - `attachments` WebhookMessageEventAttachment[]: Omitted when the message has no attachments.
        - `id` string
        - `type` 'image' | 'video' | 'audio' | 'file', required
        - `url` string, uri, required: Platform-hosted URL. Meta expires these, so treat them as short-lived.
        - `previewUrl` string, uri
      - `senderId` string: Platform id of the sender.
      - `senderName` string: Display name of the sender.
      - `createdAt` string, date-time, required: When the message was sent.
      - `storyReply` boolean: True when the message replies to a story.
      - `isStoryMention` boolean: True when the message is a story mention.
      - `source` 'dashboard' | 'api' | 'automation' | 'sync', required: `sync` for messages received from the platform; `dashboard`, `api`, or `automation` for messages sent through PostZen.
      - `automationId` string: Comment automation that sent the message. Present only when `source` is `automation`.
      - `recipientId` string: Platform id of the commenter the automation messaged. Present only when `source` is `automation`.

## Acknowledgement `2XX`

Acknowledges the delivery. Any other status, or no response within 10 seconds, schedules a retry.

---

[API](https://skmtc.dev/postzen/apis/postzen-public-api.md) · [All operations](https://skmtc.dev/postzen/apis/postzen-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/postzen/apis/postzen-public-api/revisions/40863e3710ec?raw)