# Unified inbox

> Read and answer DMs, comments, reviews and mentions from every network through one API, and receive them in real time with webhooks.

The inbox brings four kinds of activity from every connected account into one model, in the [Inbox](/docs/api-reference/inbox/) reference (MCP toolset `inbox`):

| Kind | Networks | Endpoints |
|---|---|---|
| **Conversations and messages** | Facebook, Instagram, X, Bluesky, Reddit, Discord, Mastodon, TikTok business | `/v1/inbox/conversations…` |
| **Comments** | Most publishing networks | `/v1/inbox/posts…`, `/v1/inbox/comments…` |
| **Reviews** | Google Business Profile, Facebook | `/v1/inbox/reviews…` |
| **Mentions** | Where the network reports them | `/v1/inbox/mentions…` |

You only see items of accounts in profiles you can access.

## Conversations

```bash
curl "https://api.socialit.com/v1/inbox/conversations?status=open&platform=instagram&unread=true" \
  -H "Authorization: Bearer $SOCIALIT_API_KEY"
```

Filter by `profile_id`, `account_id`, `platform`, `status` (`open`, `archived`, `snoozed`), `folder` (`inbox` or `requests` for Facebook and Instagram message requests), `assignee_id`, `label` and `unread`. `GET /v1/inbox/conversations/search?q=…` searches messages and participants.

Triage with `PATCH /v1/inbox/conversations/{conversationId}`: `status`, `snoozed_until`, `assignee_id`, `labels` and `contact_id`. Mark read with `POST …/read` (sends read receipts where the network supports them).

## Send messages

```bash
curl -X POST https://api.socialit.com/v1/inbox/conversations/conv_4Xb1Nq8Lm2Vc7Rt9Ys3Kd6Hp0Zw/messages \
  -H "Authorization: Bearer $SOCIALIT_API_KEY" \
  -H "Idempotency-Key: reply-4711" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Yes, we ship to Canada!", "quick_replies": [{ "title": "Track my order", "payload": "TRACK" }] }'
```

Messages take `text`, `media_ids` (upload with [Media](/docs/api-reference/media/)) or `attachment_url`, and network features such as `buttons`, `quick_replies` and `reply_to`. Start a new thread, such as a cold DM, with `POST /v1/inbox/conversations`.

Socialit enforces each network's messaging rules. Messenger and Instagram allow free-form replies within 24 hours of the customer's last message; after that Meta needs a `message_tag`. Delete, react and fetch attachments under `…/messages/{messageId}`.

## Comments

- `GET /v1/inbox/posts` lists posts with comments; `GET /v1/inbox/posts/{postId}/comments` reads a post's comments live. `postId` can be an inbox post, a Socialit post (`pst_…`) or a network post ID with `account_id`.
- `GET /v1/inbox/comments` is a feed across every post, with `status`, `read`, `hidden` and assignment filters.
- Act on a comment: `…/replies`, `…/hide`, `…/like`, `…/pin` (TikTok), `…/moderation` (YouTube held-for-review), `DELETE`, and `…/private-reply`, which answers a Facebook or Instagram commenter by DM.

To answer comments automatically (comment-to-DM), see [CRM and automations](/docs/crm-automations/#comment-automations).

## Reviews and mentions

`GET /v1/inbox/reviews` returns reviews with a rating `summary`; `POST /v1/inbox/reviews/{reviewId}/reply` replies (or replaces the reply), and `DELETE …/reply` removes it on Google Business Profile. Mentions are listed at `GET /v1/inbox/mentions` and answered with `POST /v1/inbox/mentions/reply`.

## Real-time ingestion with webhooks

Socialit receives the networks' own webhooks (Meta, X, LinkedIn, TikTok, Google Business, Discord, YouTube) at its own endpoints, deduplicates them, normalizes them and stores them. Networks without push (Reddit, Bluesky, Mastodon, Threads, LinkedIn organizations) are polled every 5 to 30 minutes. Either way, your app gets one stream of [webhook events](/docs/api-reference/webhook-events/#events-inbox):

| Event | Payload (`data`) |
|---|---|
| `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`, `message.edited`, `message.deleted` | `{ message, conversation, account }` |
| `reaction.received` | `{ reaction, message, conversation, account }` |
| `conversation.created`, `conversation.updated` | `{ conversation, account }` (+ `changes`) |
| `comment.received`, `comment.replied`, `comment.hidden`, `comment.unhidden`, `comment.deleted` | `{ comment, post, account }` |
| `review.received`, `review.updated`, `review.replied` | `{ review, account }` |
| `mention.received` | `{ mention, account }` |

Create an endpoint with `POST /v1/webhooks` and `events: ["message.received", "comment.received"]`, and verify signatures as described in [Webhooks](/docs/webhooks/). The first sync of a new account imports history silently: no events, nothing unread.

Need it sooner? `POST /v1/inbox/sync` queues an immediate poll for the polled networks, and `GET /v1/inbox/counts` returns unread and open counters for badges.

## Account messaging settings

Configure the entry points of a conversation per account: Messenger persistent menu, get-started button, greeting and ice breakers, and Instagram ice breakers (`/v1/accounts/{accountId}/messenger-menu`, `…/instagram-ice-breakers`, …).

## Contacts

Every sender becomes a [contact](/docs/crm-automations/#contacts) with channels per network, tags and custom fields. Link a conversation to a contact with `contact_id`.

---

Source: https://socialit.com/docs/inbox/
