# Inbox

One inbox for DMs, comments, reviews and mentions across every connected account, fed by webhooks and answered through the API.

The inbox gathers every conversation and every public reaction to your content into one model. DMs from Instagram, Facebook, X, WhatsApp and the rest become **conversations** with **messages**. Replies under your posts become **comments**. Google and Facebook ratings become **reviews**. Tags of your account elsewhere become **mentions**. You read and answer all of them with the same endpoints, whatever the platform.

## What each platform supports

| Platform | DMs | Comments | Reviews | Mentions |
| --- | --- | --- | --- | --- |
| Instagram | Send and receive, media, quick replies, buttons, cards, reactions | Reply, hide, delete, private reply. Liking is in limited release | – | Comment and caption mentions |
| Facebook | Send and receive, media, quick replies, buttons, cards, reactions, message requests | Reply, like, hide, delete, private reply | List and reply | Post and comment mentions (read only) |
| X | Send and receive | Reply, like, hide, delete | – | – |
| Threads | – | Reply, hide, delete | – | – |
| TikTok | Reply only, business accounts | Reply, like, hide, pin, delete your own | – | – |
| YouTube | – | Reply, delete, moderate | – | – |
| LinkedIn | – | Reply, react, delete (company pages) | – | Company page mentions |
| Bluesky | Text only | Reply, like, delete | – | – |
| Telegram (coming soon) | Send and receive, media, keyboards, edits | – | – | – |
| WhatsApp | Send and receive, templates, interactive messages | – | – | – |
| Slack | DMs and bot mentions | – | – | – |
| SMS, iMessage, RCS | Send and receive | – | – | – |
| Google Business Profile | – | – | List, reply, delete reply | – |
| Reddit | Paused | Paused | – | – |

Reddit closed its API to third-party apps, so Reddit messages and comments stop syncing until access returns. Telegram and Discord are coming soon and cannot be connected yet; once Discord opens, its bot will send DMs but not read replies (see [Discord](https://pozy.ai/docs/platforms/discord)). Platform pages list the exact limits, for example [Instagram](https://pozy.ai/docs/platforms/instagram) and [WhatsApp](https://pozy.ai/docs/whatsapp).

## How the pieces fit

- A **conversation** belongs to one connected account, and the account belongs to a profile. Filter by `profileId` to get one customer's inbox, or by `accountId` for one account.
- A **contact** is the person behind one or more conversations, with tags and custom fields. See [Contacts](https://pozy.ai/docs/inbox/contacts).
- Every send from automations is attributed: `message.sent` webhooks carry `sentVia` (`human`, `api`, `broadcast`, `sequence`, `workflow`, `comment_automation`, `bulk-api`) plus the ids of what sent it.

## Build on webhooks, not polling

The fastest and cheapest inbox is written by webhooks and read from your own database. Polling every conversation burns through your [rate limit](https://pozy.ai/docs/getting-started/rate-limits) and still lags.

### Subscribe once
Create one webhook endpoint for `conversation.started`, `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `comment.received` and the `review.*` events. See [Set up webhooks](https://pozy.ai/docs/webhooks).

### Write each event to your store
Dedupe on the event id (`X-Pozy-Event-Id`), acknowledge with a `2xx` within 5 seconds and process the event on a worker. `profiles[0].externalId` tells you which of your customers it belongs to when you use [one profile per customer](https://pozy.ai/docs/build).

### Backfill and reconcile
When accounts connect, page through `GET /v1/inbox/conversations` with `cursor`, then fetch messages per conversation. Run the same sweep on a schedule to catch anything a missed delivery left behind.

### Send through the API
Replies, comments and review answers go out with the endpoints on the following pages. Delivery status comes back on the same webhook stream.

> **History from before the connection:**
> 
> When an Instagram or Facebook account connects, Pozy replays the DM history the platform already holds: up to 500 conversations per account and the newest 500 messages in each. The replay runs in the background, arrives already marked as read and fires no webhooks, so read it from the list endpoint. Run your onboarding sweep again about an hour later to pick it up.

## Account errors inside list responses

List endpoints aggregate many accounts at once. When one account fails (an expired token, a platform outage), the rest still return. Check `meta`:

```json
{
  "meta": {
    "accountsQueried": 3,
    "accountsFailed": 1,
    "failedAccounts": [{ "accountId": "6650c1e2a3b4c5d6e7f80a22", "platform": "instagram", "error": "The account needs to be reconnected", "code": null, "retryAfter": null }]
  }
}
```

An account in `failedAccounts` usually needs to be reconnected. See [Account health](https://pozy.ai/docs/connect/account-health).

## In this section

- [Messages](https://pozy.ai/docs/inbox/messages): List conversations, read messages, reply with text, media and buttons, hand over threads.
- [Comments](https://pozy.ai/docs/inbox/comments): Read, reply, hide, like, pin and moderate comments, and DM a commenter.
- [Reviews](https://pozy.ai/docs/inbox/reviews): Answer Google Business Profile and Facebook reviews.
- [Mentions](https://pozy.ai/docs/inbox/mentions): Mentions of your accounts, X search and engagement.
- [Contacts](https://pozy.ai/docs/inbox/contacts): The people behind your conversations, with tags and subscription state.
- [Custom fields](https://pozy.ai/docs/inbox/custom-fields): Typed fields on contacts for segments and personalisation.

## Webhook events

| Event | When it fires |
| --- | --- |
| [`message.received`](https://pozy.ai/docs/webhooks/events#message-received) | Message received. |
| [`conversation.control_changed`](https://pozy.ai/docs/webhooks/events#conversation-control-changed) | Conversation control changed. |
| [`conversation.started`](https://pozy.ai/docs/webhooks/events#conversation-started) | Conversation started. |
| [`message.sent`](https://pozy.ai/docs/webhooks/events#message-sent) | Message sent. |
| [`message.edited`](https://pozy.ai/docs/webhooks/events#message-edited) | Message edited. |
| [`message.deleted`](https://pozy.ai/docs/webhooks/events#message-deleted) | Message deleted. |
| [`message.delivered`](https://pozy.ai/docs/webhooks/events#message-delivered) | Message delivered. |
| [`message.read`](https://pozy.ai/docs/webhooks/events#message-read) | Message read. |
| [`message.played`](https://pozy.ai/docs/webhooks/events#message-played) | Message played. |
| [`message.failed`](https://pozy.ai/docs/webhooks/events#message-failed) | Message delivery failed. |
| [`reaction.received`](https://pozy.ai/docs/webhooks/events#reaction-received) | Reaction received. |
| [`referral.received`](https://pozy.ai/docs/webhooks/events#referral-received) | Referral received. |
| [`comment.received`](https://pozy.ai/docs/webhooks/events#comment-received) | Comment received. |
| [`review.new`](https://pozy.ai/docs/webhooks/events#review-new) | Review new. |
| [`review.updated`](https://pozy.ai/docs/webhooks/events#review-updated) | Review updated. |
| [`review.deleted`](https://pozy.ai/docs/webhooks/events#review-deleted) | Review deleted. |
| [`review.restored`](https://pozy.ai/docs/webhooks/events#review-restored) | Review restored. |