> ## Documentation Index
> Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Unified inbox

> Read and respond to comments, DMs, reviews, and mentions across platforms through a single social media inbox API.

The inbox is a unified social inbox API: a single endpoint that returns comments, direct messages, mentions, and reviews from every connected platform in one normalized `Interaction` shape, so you build inbox logic once instead of per platform.

SocialAPI provides a unified inbox API for reading and responding to all inbound engagement across your connected accounts. Comments, DMs, reviews, and mentions are accessed through consistent endpoints with the same response shape regardless of platform.

SocialAPI proxies comments, reviews, and mentions live from the platform API, so you always see the latest state. DM conversations and messages are stored in SocialAPI's database to support threading and pagination.

## Comments

List comments across all connected accounts, reply, and moderate.

### Endpoints

| Method   | Path                                                  | Description                                       |
| -------- | ----------------------------------------------------- | ------------------------------------------------- |
| `GET`    | `/v1/inbox/comments`                                  | List posts that received comments across accounts |
| `GET`    | `/v1/inbox/comments/:postId`                          | List comments on a specific post                  |
| `GET`    | `/v1/inbox/comments/:postId/:commentId/replies`       | List replies to a specific comment                |
| `POST`   | `/v1/inbox/comments/:postId`                          | Reply to a comment on a post                      |
| `DELETE` | `/v1/inbox/comments/:postId/:commentId`               | Delete a comment                                  |
| `POST`   | `/v1/inbox/comments/:postId/:commentId/hide`          | Hide a comment                                    |
| `DELETE` | `/v1/inbox/comments/:postId/:commentId/hide`          | Unhide a comment                                  |
| `POST`   | `/v1/inbox/comments/:postId/:commentId/like`          | Like a comment                                    |
| `DELETE` | `/v1/inbox/comments/:postId/:commentId/like`          | Unlike a comment                                  |
| `POST`   | `/v1/inbox/comments/:postId/:commentId/private-reply` | Send a private DM in reply to a comment           |

`:postId` accepts a platform post ID (e.g., `17895695668004550`). `:commentId` accepts a SocialAPI interaction ID (`sapi_cmt_...`). See [Interaction IDs](/guides/interaction-ids) for the encoding.

### Platform capabilities

| Platform      | Reply | Hide        | Like | Delete      | Private reply |
| ------------- | ----- | ----------- | ---- | ----------- | ------------- |
| Instagram     | Yes   | Yes         | No   | Yes         | Yes           |
| Facebook      | Yes   | Yes         | Yes  | Yes         | Yes           |
| Threads       | Yes   | Conditional | No   | Conditional | No            |
| Google        | Yes   | No          | No   | No          | No            |
| LinkedIn Page | Yes   | No          | Yes  | Yes         | No            |
| LinkedIn      | Soon  | No          | No   | No          | No            |
| YouTube       | Yes   | Yes         | No   | Yes         | No            |
| X / Twitter   | Yes   | No          | No   | No          | No            |
| TikTok        | No    | No          | No   | No          | No            |

For Threads, Hide is available on comments not owned by the user; Delete is available on own replies. LinkedIn Page (`linkedin_page`) is the organization page connector and is available in beta. Each comment in the response includes a `capabilities` object so your code can check what is actually allowed for that specific item.

### Example: list and reply

```bash theme={null}
# List posts that have comments
curl https://api.social-api.ai/v1/inbox/comments \
  -H "Authorization: Bearer $SOCAPI_KEY"

# List comments on one post
curl "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a specific comment on a post (postId is the platform post ID)
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "comment_id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U",
    "text": "Thanks for the feedback!"
  }'

# Hide a comment
curl -X POST "https://api.social-api.ai/v1/inbox/comments/{postId}/{commentId}/hide" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }'
```

## Direct messages

Read conversations and send messages across platforms that support DMs.

### Endpoints

| Method  | Path                                   | Description                                                  |
| ------- | -------------------------------------- | ------------------------------------------------------------ |
| `GET`   | `/v1/inbox/conversations`              | List DM conversations                                        |
| `GET`   | `/v1/inbox/conversations/:id`          | Get a single conversation                                    |
| `PATCH` | `/v1/inbox/conversations/:id`          | Update a conversation (set status to `active` or `archived`) |
| `POST`  | `/v1/inbox/conversations/:id/read`     | Mark a conversation as read                                  |
| `GET`   | `/v1/inbox/conversations/:id/messages` | Get messages in a conversation                               |
| `POST`  | `/v1/inbox/conversations/:id/messages` | Send a message                                               |

### List conversations query parameters

| Parameter    | Type    | Default  | Description                                        |
| ------------ | ------- | -------- | -------------------------------------------------- |
| `account_id` | string  |          | Filter by connected account ID                     |
| `platform`   | string  |          | Filter by platform (e.g., `instagram`, `facebook`) |
| `status`     | string  | `active` | Conversation status: `active` or `archived`        |
| `limit`      | integer | `25`     | Page size (1-100)                                  |
| `cursor`     | string  |          | Pagination cursor from the previous response       |

### Platform support

| Platform  | DMs supported | Notes                                           |
| --------- | ------------- | ----------------------------------------------- |
| Instagram | Yes           | 24-hour messaging window for non-followers      |
| Facebook  | Yes           | Via Messenger Send API, 24-hour response window |
| LinkedIn  | No            | Platform API does not expose DMs                |
| TikTok    | No            | Not available via API                           |
| Google    | No            | Not applicable                                  |
| Threads   | No            | Not available via API                           |
| YouTube   | No            | Not available via API                           |

### Sending text and attachments

A message can carry text, an attachment, or both. Provide `text`, `attachment_url`, or both: at least one is required.

| Field            | Required    | Description                                                                     |
| ---------------- | ----------- | ------------------------------------------------------------------------------- |
| `account_id`     | Yes         | Connected account that owns the conversation                                    |
| `text`           | Conditional | Message body. Required unless `attachment_url` is set                           |
| `attachment_url` | Conditional | Publicly reachable URL of a media file to attach. Required unless `text` is set |

On Facebook and Instagram, `attachment_url` is delivered as a Messenger attachment. The attachment type (image, video, audio, or file) is inferred from the URL file extension, so use a direct media link with the correct extension (for example `.jpg`, `.mp4`, `.mp3`). URLs without a recognized media extension are sent as a generic file. The media must be hosted on a publicly reachable URL (max 25 MB); the platform fetches it directly.

### Example: list conversations and send a message

```bash theme={null}
# List conversations
curl https://api.social-api.ai/v1/inbox/conversations \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Send a text message in a conversation
curl -X POST https://api.social-api.ai/v1/inbox/conversations/sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_abc123", "text": "Your order has shipped!" }'

# Send an image attachment (text optional)
curl -X POST https://api.social-api.ai/v1/inbox/conversations/sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_abc123", "text": "Here is your receipt", "attachment_url": "https://cdn.example.com/receipt.jpg" }'
```

## Reviews

Read and reply to reviews on platforms that support them.

### Endpoints

| Method | Path                          | Description       |
| ------ | ----------------------------- | ----------------- |
| `GET`  | `/v1/inbox/reviews`           | List reviews      |
| `POST` | `/v1/inbox/reviews/:id/reply` | Reply to a review |

### Platform support

| Platform   | Reviews                       |
| ---------- | ----------------------------- |
| Google     | Yes (Google Business Profile) |
| All others | No                            |

### Example

```bash theme={null}
# List reviews
curl https://api.social-api.ai/v1/inbox/reviews \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a review
curl -X POST https://api.social-api.ai/v1/inbox/reviews/sapi_rev_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/reply \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "text": "Thank you for the review!" }'
```

## Mentions

Read mentions of a connected account, and reply to them as a public comment.

### Endpoints

| Method | Path                              | Description                            |
| ------ | --------------------------------- | -------------------------------------- |
| `GET`  | `/v1/accounts/:id/mentions`       | List mentions for a connected account  |
| `POST` | `/v1/accounts/:id/mentions/reply` | Reply to a mention as a public comment |

Mentions are scoped to a single connected account, not the workspace.

Replying works even when the mention is on someone else's post, where the normal
comment-reply endpoint is not allowed. Pass `media_id` (the post the mention is
on, or the `sapi_mnt_` id from the list response) and `text`. Set `comment_id`
only when the mention was inside a comment; omit it to reply to a mention in the
post caption. A reply consumes 1 interaction credit.

### Platform support

| Platform    | List mentions | Reply to mention |
| ----------- | ------------- | ---------------- |
| Instagram   | Yes           | Yes              |
| Facebook    | Yes           | Yes              |
| X / Twitter | Yes           | No               |
| All others  | No            | No               |

### Example

```bash theme={null}
# List mentions
curl "https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions" \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a comment mention as a public comment
curl -X POST https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions/reply \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "17895695668004550", "comment_id": "17858893269577012", "text": "Thanks for the shout-out!"}'
```

## Interaction IDs

Every interaction returned by the inbox has a stable ID with a type prefix:

| Prefix      | Type    |
| ----------- | ------- |
| `sapi_cmt_` | Comment |
| `sapi_dm_`  | DM      |
| `sapi_rev_` | Review  |
| `sapi_mnt_` | Mention |

The suffix encodes the platform and the platform-native ID, so you can route actions without a database lookup. See [Interaction IDs](/guides/interaction-ids) for the full encoding scheme.

## Webhooks

SocialAPI can notify your server when new inbound interactions arrive (new comment, new DM, new review). Register a webhook endpoint and subscribe to the event types you care about. See [Webhooks](/guides/webhooks) for setup and event reference.

## Related

* [Platform support](/guides/platforms) for the full capability matrix
* [Interaction IDs](/guides/interaction-ids) for the ID encoding scheme
* [Webhooks](/guides/webhooks) for real-time event delivery
* [API Reference](/api-reference/introduction) for complete endpoint schemas