# Inbox webhooks

Events for DMs, comments, reviews, conversations, contacts, sequences and workflows, plus email sends, opens and bounces, and calendar and file changes.

## Events

### Messages

Message payloads carry an `account` block with `accountId` and `profileId`. Facebook and Instagram accounts with a Facebook Page also carry `pageId`.

| Event | Description |
| --- | --- |
| [`message.received`](/webhooks/inbox/message-received) | A new inbox message arrived. |
| [`message.sent`](/webhooks/inbox/message-sent) | An outgoing message was sent from the inbox. |
| [`message.edited`](/webhooks/inbox/message-edited) | A sender edited a previously sent message. |
| [`message.deleted`](/webhooks/inbox/message-deleted) | A sender deleted (unsent) a message. |
| [`message.delivered`](/webhooks/inbox/message-delivered) | An outgoing message was delivered to the recipient. |
| [`message.read`](/webhooks/inbox/message-read) | An outgoing message was read by the recipient. |
| [`message.played`](/webhooks/inbox/message-played) | An outgoing WhatsApp message was played by the recipient. |
| [`message.failed`](/webhooks/inbox/message-failed) | An outgoing message failed to deliver (WhatsApp, SMS, RCS, iMessage). |

### Engagement

| Event | Description |
| --- | --- |
| [`reaction.received`](/webhooks/inbox/reaction-received) | A participant added or removed an emoji reaction on a message. |
| [`referral.received`](/webhooks/inbox/referral-received) | Someone opened an existing conversation through a `ref` link or ad click. |
| [`comment.received`](/webhooks/inbox/comment-received) | A new comment arrived on a tracked post. |
| [`mention.received`](/webhooks/inbox/mention-received) | A connected account was mentioned (Instagram, Facebook, LinkedIn). |

### Conversations

| Event | Description |
| --- | --- |
| [`conversation.started`](/webhooks/inbox/conversation-started) | A new conversation began between an account and a contact. |
| [`conversation.control_changed`](/webhooks/inbox/conversation-control-changed) | Control of a conversation moved: Meta Business Agent on WhatsApp, or Meta's conversation routing on Facebook and Instagram. |

### Reviews

| Event | Description |
| --- | --- |
| [`review.new`](/webhooks/inbox/review-new) | A new review was posted on a connected account. |
| [`review.updated`](/webhooks/inbox/review-updated) | A review was edited, or its reply was added, edited or removed. |
| [`review.deleted`](/webhooks/inbox/review-deleted) | Google stopped returning a review. |
| [`review.restored`](/webhooks/inbox/review-restored) | A review reported by `review.deleted` came back. |

### Email calendar and files

These events come from [Google](/platforms/google), [Microsoft](/platforms/microsoft) and [IMAP](/platforms/imap) accounts. Calendar, file and contact events are Google and Microsoft only. New email arrives as [`message.received`](/webhooks/inbox/message-received).

| Event | Description |
| --- | --- |
| [`email.sent`](/webhooks/inbox/email-sent) | A mail left through the email API: send, reply, forward, draft or scheduled. |
| [`email.opened`](/webhooks/inbox/email-opened) | A message sent with `trackOpens` was opened. |
| [`email.link_clicked`](/webhooks/inbox/email-link-clicked) | A link in a message sent with `trackLinks` was followed. |
| [`email.thread_replied`](/webhooks/inbox/email-thread-replied) | Someone wrote in the thread of a message sent with `trackReplies`. |
| [`email.send_failed`](/webhooks/inbox/email-send-failed) | A scheduled email could not be sent at its time. |
| [`email.bounced`](/webhooks/inbox/email-bounced) | A mail the mailbox sent bounced, once per failed recipient. |
| [`email.updated`](/webhooks/inbox/email-updated) | A message was read, starred, labelled, archived, trashed or moved. Google and Microsoft. |
| [`email.deleted`](/webhooks/inbox/email-deleted) | A message was deleted for good. Google and Microsoft. |
| [`calendar.event.created`](/webhooks/inbox/calendar-event-created) | An event was added to a watched calendar. |
| [`calendar.event.updated`](/webhooks/inbox/calendar-event-updated) | An event on a watched calendar changed. |
| [`calendar.event.deleted`](/webhooks/inbox/calendar-event-deleted) | An event was deleted or cancelled. |
| [`file.created`](/webhooks/inbox/file-created) | A file appeared in Drive or OneDrive. |
| [`file.updated`](/webhooks/inbox/file-updated) | A file changed. |
| [`file.deleted`](/webhooks/inbox/file-deleted) | A file was deleted. |
| [`file.picked`](/webhooks/inbox/file-picked) | The user picked Google Drive files. |

### Contacts and automations

| Event | Description |
| --- | --- |
| [`contact.updated`](/webhooks/inbox/contact-updated) | The contact sync added or changed a contact. |
| [`contact.deleted`](/webhooks/inbox/contact-deleted) | A provider contact was deleted. |
| [`contact.tag_added`](/webhooks/inbox/contact-tag-added) | A tag was added to a contact. |
| [`contact.tag_removed`](/webhooks/inbox/contact-tag-removed) | A tag was removed from a contact. |
| [`contact.field_changed`](/webhooks/inbox/contact-field-changed) | A contact custom field changed value. |
| [`sequence.enrolled`](/webhooks/inbox/sequence-enrolled) | A contact was enrolled in a sequence. |
| [`sequence.exited`](/webhooks/inbox/sequence-exited) | A contact left a sequence; `exitReason` says why. |
| [`workflow.run.started`](/webhooks/inbox/workflow-run-started) | A workflow run started. |
| [`workflow.run.completed`](/webhooks/inbox/workflow-run-completed) | A workflow run ended. |
| [`workflow.run.failed`](/webhooks/inbox/workflow-run-failed) | A workflow run failed. |

## How it behaves

<Accordions>
<Accordion title="Not every platform sends every event" id="not-every-platform-sends-every-event">

Zernio forwards what each platform exposes, and each event page names its platforms. Review events come from Google Business Profile only.

`conversation.started` covers every DM platform with one event.

</Accordion>

<Accordion title="A legacy AppSumo plan gates the inbox" id="a-legacy-appsumo-plan-gates-the-inbox">

Messages, engagement, conversations, reviews, contact tags and fields, sequences and workflows need inbox access. Calendar, file and contact sync events (`contact.updated`, `contact.deleted`) do not.

Without it, `POST /v1/webhooks/settings` refuses the subscription with a `403` and code `feature_not_available`. A legacy AppSumo plan keeps the inbox off until support enables it ([pricing](/pricing)).

</Accordion>

<Accordion title="Pre-connect history fires nothing" id="pre-connect-history-fires-nothing">

When an Instagram or Facebook account connects, Zernio replays the DM history it already holds into the inbox. That history emits neither `conversation.started` nor `message.received`, the opposite of the [post backfill](/webhooks/social/post-external-created).

Read replayed DMs from [List inbox conversations](/messages/list-inbox-conversations). They are stored as already read, so they never affect unread counts.

</Accordion>

<Accordion title="Each mention fires once" id="each-mention-fires-once">

[`mention.received`](/webhooks/inbox/mention-received) fires once per mention and account, for a post, caption or comment on Instagram, Facebook or LinkedIn. It carries the same fields as [List mentions](/mentions/list-inbox-mentions) items.

Instagram and Facebook arrive in real time. LinkedIn arrives from its webhook or from polling, so it can take minutes. A newly connected LinkedIn account can receive mentions from the last 48 hours once.

</Accordion>

<Accordion title="Reactions arrive as their own event" id="reactions-arrive-as-their-own-event">

[`reaction.received`](/webhooks/inbox/reaction-received) is never sent as `message.received`, so a thumbs-up is never treated as an inbound DM. Branch on it separately.

</Accordion>

<Accordion title="Another app can own the conversation (standby)" id="another-app-can-own-the-conversation-standby">

Meta lets one app answer a conversation while the others only observe: Meta Business Agent on WhatsApp, conversation routing on Facebook and Instagram.

Zernio still delivers every inbound message as `message.received` flagged `metadata.standby: true`, and runs no automation on it.

On Facebook, and Instagram connected with Facebook Login, a send takes control back when Meta allows it. You can also call [Change who answers a conversation](/messages/set-conversation-thread-control).

Instagram Login cannot take control: the owner has to pass it.

[`conversation.control_changed`](/webhooks/inbox/conversation-control-changed) tells you when Meta moves a thread to or from Zernio.

</Accordion>

<Accordion title="WhatsApp status events carry Meta's pricing" id="whatsapp-status-events-carry-metas-pricing">

- On WhatsApp, `message.sent`, `message.delivered`, `message.read`, `message.played` and `message.failed` carry `pricing` (`billable`, `pricingModel`, `category`, `type`) and `billingConversation` (`id`, `expiresAt`, `originType`).
- Both keys are always present on WhatsApp and absent elsewhere. They are null when Meta left the object out, which it does on most statuses.
- `billingConversation` is Meta's billing window, not the Zernio `conversation` block.
- For totals over a period, use `GET /v1/whatsapp/pricing-analytics` ([WhatsApp phone numbers](/platforms/whatsapp/phone-numbers#pricing-analytics)).

</Accordion>

<Accordion title="`message.sent` names what sent it" id="messagesent-names-what-sent-it">

[`message.sent`](/webhooks/inbox/message-sent) carries `message.sentVia` and five attribution keys. On `message.received` all attribution keys are `null`.

</Accordion>

<Accordion title="Interactive replies ride on `message.received`" id="interactive-replies-ride-on-messagereceived">

Button and list taps, flow responses, orders and referrals that arrive with a message land under `metadata` on [`message.received`](/webhooks/inbox/message-received). Only a referral without a message becomes `referral.received`.

</Accordion>

<Accordion title="Email, calendar and file events" id="email-calendar-and-file-events">

- Every payload carries `account` with `accountId`, `profileId`, `platform` (`google`, `microsoft` or `imap`) and `username`, the mailbox address.
- Calendar, file and contact events carry the changed object's `id` and `changeType`, not the object. Fetch it for its current state.
- Calendar events cover every calendar the user shows on Google, and the default calendar on Outlook. `calendarId` names the calendar.
- Providers can notify the same change twice. Key your handling on the object `id`.
- Contact events come from a sync that runs every 15 minutes, so they arrive up to 15 minutes after the change.

</Accordion>

<Accordion title="One event per real change" id="one-event-per-real-change">

- Contact events fire once per tag or field a write actually changed. Writing a value the contact already has fires nothing.
- Renaming or deleting a tag, or clearing a custom field, fires one event per contact it changed.
- Creating a contact with tags fires nothing. Only changes to an existing contact do.
- `source` says who made the change: `api` (the API or dashboard), `workflow` (an `add_tag`, `remove_tag` or `set_field` node) or `automation` (a comment-automation link click that tags the clicker).

</Accordion>

<Accordion title="Contact, sequence and workflow payloads carry ids" id="contact-sequence-and-workflow-payloads-carry-ids">

Contact, sequence and workflow events carry no `account` block. `contact.id`, `sequence.id` and `workflow.id` are the keys. Read the full record with [Get contact](/contacts/get-contact), [Get sequence](/sequences/get-sequence) or [Get workflow](/workflows/get-workflow).

An endpoint scoped to accounts still receives `sequence.*` and `workflow.run.*` for the account that sent them.

</Accordion>

<Accordion title="Runs report how they ended" id="runs-report-how-they-ended">

`conversation` is `null` while a comment-triggered run has not sent the private reply that opens its conversation.

`trigger.type` is `null` when the workflow was deleted while the run was live. Statuses and `error` are on each run event's page.

</Accordion>
</Accordions>

## Related

- [Webhooks](/webhooks): create an endpoint, retries, signatures.
- [Send a message](/messages/send-inbox-message): reply to `message.received` with `accountId` and `message`.
- [List inbox conversations](/messages/list-inbox-conversations): the same conversations on demand.
- [Comment automations](/comment-automations/list-comment-automations): DM people who comment a keyword.
- [Chat SDK](/resources/integrations/chat-sdk): a bot framework that consumes these events.
- [Workflows](/products/automations/workflows): triggers, nodes and runs.
- [Zero content retention](/security/zero-content-retention): with it on for the team or a profile, `message.*`, `comment.received` and `mention.received` are the only copy of the content.
- [Google](/platforms/google/webhooks) and [Microsoft](/platforms/microsoft/webhooks) push notifications, and [IMAP](/platforms/imap/webhooks) mailboxes
- [List calendar events](/calendar/list-calendar-events)
- [List files](/files/list-files)
- [List contacts](/contacts/list-contacts)
- [Contacts](/contacts/list-contacts) and [Sequences](/sequences/list-sequences): the records the contact, sequence and workflow events describe.