Inbox webhooks

Inbox events cover everything that lands in or leaves the inbox: DMs and their delivery lifecycle, conversations, emoji reactions, comments on tracked posts, and reviews. Subscribe with POST /v1/webhooks/settings and the event names below (first event); delivery, retries and signatures are the same for every event (how webhooks behave). Message payloads carry an account block with accountId and profileId, so one endpoint can serve many profiles.

Events

How it behaves

Not every platform sends every event

Zernio forwards what each platform exposes:

conversation.started covers every DM platform (Instagram, Messenger, Telegram, WhatsApp, X, Reddit, Bluesky) with one event.

A legacy AppSumo plan gates the inbox

Every event on this page except conversation.control_changed needs inbox access. Without it POST /v1/webhooks/settings refuses the subscription itself with a 403 and code feature_not_available, rather than accepting it and delivering nothing. A legacy AppSumo plan keeps the inbox off until support enables it (pricing).

Pre-connect history fires nothing

Reactions arrive as their own event

Zernio sends reaction.received as its own event, never as message.received, so branch on it separately and a thumbs-up is never treated as an inbound DM. reaction.action is added or removed. reaction.platformMessageId is the platform-native id of the reacted-to message and is always present; reaction.messageId is the Zernio message id when it can be resolved. On WhatsApp, Instagram and Facebook removals the platform does not report which emoji went away, so reaction.emoji is an empty string when action is removed: match on platformMessageId to clear a reaction you mirror. TikTok sends no unicode for an AI emoji reaction, so reaction.emoji can be empty for those too.

Another app can own the conversation (standby)

Meta's handover protocol lets one app answer a conversation while the others only observe. Zernio still delivers every inbound message as message.received, flagged metadata.standby: true, and runs no automation on it: no workflow, no keyword automation.

• WhatsApp: on a number with Meta Business Agent enabled, the agent answers from Meta's side and its replies arrive as message.sent with source: "meta_business_agent". Sending any message takes control back, so a bot that replies to every message.received must skip standby ones or it takes the conversation away from the agent.
• Facebook and Instagram: another app on the Page, such as Page Inbox, owns the thread. A send while you are not the owner answers 409 with code not_thread_owner (details.ownerAppId names the owner when Meta reports it). Take control first with Change who answers a conversation.

conversation.control_changed tells you when control moves.

WhatsApp status events carry Meta's pricing

On WhatsApp, message.sent, message.delivered, message.read and message.failed carry two extra keys from Meta's status webhook: pricing (billable, pricingModel, category, type) and billingConversation (id, expiresAt, originType). Both keys are always present on WhatsApp and null when Meta left the object out, which it does on most statuses: Meta sends pricing on sent and on one of delivered or read. billingConversation is Meta's billing window, not the Zernio conversation block. The keys are absent on other platforms. For totals over a period, use GET /v1/whatsapp/pricing-analytics (WhatsApp phone numbers).

message.sent names what sent it

message.sent carries message.sentVia (human, api, broadcast, sequence, workflow, comment_automation, bulk-api) and five attribution keys: automationId (the comment automation), workflowId and executionId (the workflow and its run), broadcastId and sequenceId. They are always present: each is null unless that kind of sender produced the message, and on message.received all of them are null. sentVia is null for a message sent from the platform's own app and for messages stored before it shipped, so treat null as unknown, never as "sent by a human". On Instagram and Facebook the attribution can be missing when Meta's echo of a send reaches Zernio before the send itself is recorded.

Interactive replies ride on message.received

Zernio delivers button and list taps, flow responses, orders and referrals that arrive with a message under metadata on message.received (interactiveType, interactiveId, flowResponseData, order, referral). Only a referral that arrives without a message becomes referral.received.

---

message.received

A new inbox message arrived. message.text, message.attachments[] and message.sender describe it; conversation.id is the conversationId for POST /v1/inbox/conversations/{conversationId}/messages.

---

message.sent

An outgoing message was sent from the inbox, through the API or the dashboard.

---

conversation.started

A new conversation began between one of your connected accounts and a contact, in either direction, on any DM platform. A given conversation fires it once, the first time it appears. Pre-connect history never fires it (why).

---

conversation.control_changed

Control of a conversation moved under Meta's handover protocol (messaging_handovers). control.owner is who answers now: ai_agent (Meta Business Agent, WhatsApp), app (you) or other (a WhatsApp partner app, or a Messenger or Instagram receiver such as Page Inbox); control.previousOwner is who did before, null when no handover had touched the thread. control.ownerAppId is the Meta app id of the new owner when Meta names it (Page Inbox is 263902037430900), and control.metadata is the note the transferring app attached, forwarded verbatim.

• WhatsApp: Meta Business Agent took the conversation over or handed it to you, or another partner app took it. While the owner is ai_agent, the agent's replies arrive on message.sent with source: "meta_business_agent". Sending any message through the inbox takes control back; to hand it to the agent without sending, call Change who answers a conversation with action: "release".
• Facebook and Instagram: another app on the Page passed the thread to you, or took or received it. While you are not the owner, sends answer 409 not_thread_owner; call Change who answers a conversation with action: "take", or "request" to ask the owner to pass it. A repeat report of the same owner fires nothing, and a request changes nothing until the owner passes the thread.

While another app owns the conversation, inbound messages arrive on message.received with metadata.standby: true.

---

message.edited

The sender edited a previously sent message on Instagram, Facebook Messenger, Telegram or WhatsApp. The payload carries the full editHistory, oldest prior version first, and message.text is the latest version.

---

message.deleted

The sender deleted (unsent) a message: on Instagram an incoming unsend, on WhatsApp in both directions, with message.direction telling the business's deletions from the customer's. The payload keeps the pre-delete text and attachments for moderation, compliance or archival. The Zernio dashboard does not show this content.

---

message.delivered

An outgoing message was delivered to the recipient on WhatsApp, Facebook Messenger or SMS.

---

message.read

An outgoing message was read by the recipient on WhatsApp, Facebook Messenger or Instagram.

---

message.failed

An outgoing message failed to deliver on WhatsApp or SMS. error carries code, title and message from the platform, for example 131026 for a WhatsApp recipient that is not reachable; on SMS it carries the carrier's error code.

---

reaction.received

A participant added or removed an emoji reaction on a message, on Instagram, Facebook, WhatsApp, Telegram, Slack or TikTok. On TikTok a like or emoji reaction on a DM arrives only as this event, never as an empty message.received, with reaction.platformMessageId set to the TikTok id of the liked message. On Telegram the bot must be an administrator in the chat; reactions in private chats are never delivered to bots.

---

referral.received

Someone opened an existing Instagram or Facebook Messenger conversation through an ig.me or m.me ref link or a returning Messenger ad click. The payload forwards Meta's referral object verbatim: ref and source for links, ad_id and ads_context_data for ad clicks. A referral that rides an inbound message arrives on message.received under metadata.referral instead.

---

comment.received

A new comment arrived on a tracked post. On Instagram, comment.isLive: true marks a comment made during a live broadcast; the key is absent on every other comment.

comment.ad is present when the comment was made on paid content: on Instagram it carries ad.id and ad.title from the Meta webhook, on Facebook ad.promotionStatus ("active" for boosted organic posts, "ineligible" for dark post creatives). It is absent for comments on organic posts that are not currently promoted, so if (comment.ad) filters ad-driven comments.

Instagram comments may carry comment.author.instagramProfile (isFollower, isFollowing, followerCount, isVerified). Meta reveals the follow relationship only for people who have messaged the account, and commenting does not grant that consent, so the object is absent for most first-time commenters. An absent object means unknown, never "not a follower". To resolve it on demand, call Instagram follow status; to gate an auto-DM on it, use a comment automation's audience rules.

---

review.new

A new review was posted on a connected Google Business Profile account, in real time through Pub/Sub.

---

review.updated

A review changed: the reviewer edited their text or rating, or a reply was added through the API or the Google Business Profile dashboard. The payload has the same shape as review.new; when a reply is present, review.hasReply is true and review.reply is populated.

Related

• Webhooks: create an endpoint, retries, signatures.
• Send a message: reply to message.received with accountId and message.
• List inbox conversations: the same conversations on demand.
• Comment automations: DM people who comment a keyword.
• Automation webhooks: contact, sequence and workflow run events.
• Chat SDK: a bot framework that consumes these events.