# Social Inbox API: DMs, Comments, Mentions

Read and reply to your Instagram and Facebook DMs, comments, and mentions, plus LinkedIn company-page comments and mentions, all from the API. Conversations are served from OmniSocials, so you read at your own pace without hitting each platform's rate limits, and replies go out through your connected accounts.

TikTok social inbox is coming soon.

## Enabling inbox access

The inbox scopes are opt-in. When you create an API key, turn on **Social Inbox access** to grant both inbox scopes. Existing keys are not given these scopes automatically.

| Scope | Grants |
|-------|--------|
| `inbox:read` | List conversations and read messages |
| `inbox:write` | Mark conversations read and send replies |

When you connect through OAuth or the MCP server, inbox access is governed by the `access_social_inbox` workspace permission instead of scopes. Company owners and admins have it by default.

## Listing conversations

Returns one entry per conversation, newest activity first.

```bash
curl "https://api.omnisocials.com/v1/inbox/conversations?platform=instagram&unread=true&limit=25" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "conversation_id": "instagram_17841400000_17841464825884163",
      "platform": "instagram",
      "type": "dm",
      "participant": {
        "id": "17841400000",
        "name": "Amelia Rivera",
        "username": "amelia.rivera",
        "profile_picture": "https://..."
      },
      "unread_count": 2,
      "last_message": {
        "id": "78027900",
        "direction": "incoming",
        "text": "Do you ship internationally?",
        "timestamp": "2026-07-19T17:05:51Z",
        "is_read": false
      },
      "post": null
    }
  ],
  "pagination": { "next_cursor": "MjAyNi0wNy0xOF...", "has_more": true, "limit": 25 }
}
```

Query parameters (all optional):

| Parameter | Description |
|-----------|-------------|
| `platform` | `instagram`, `facebook`, or `linkedin` |
| `type` | `dm`, `comment`, or `mention` |
| `unread` | `true` returns only conversations with unread incoming messages |
| `limit` | Conversations per page, 1 to 100 (default 25) |
| `cursor` | The `next_cursor` from a previous response |

`post` is present for comment and mention conversations (the post the interaction is on) and `null` for DMs.

## Cursor pagination

The inbox list endpoints use cursor pagination, not offset. Every response carries a `pagination` object:

```json
"pagination": { "next_cursor": "MjAyNi0w...", "has_more": true, "limit": 25 }
```

To fetch the next page, pass `next_cursor` back as the `cursor` query parameter. When `has_more` is `false`, `next_cursor` is `null` and you have reached the end.

## Reading a conversation

Returns the full message history, oldest first. Also cursor-paginated (default `limit` 50).

```bash
curl "https://api.omnisocials.com/v1/inbox/conversations/CONVERSATION_ID/messages" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

Response:

```json
{
  "data": [
    {
      "id": "20457105",
      "conversation_id": "instagram_17841400000_17841464825884163",
      "platform": "instagram",
      "type": "dm",
      "direction": "incoming",
      "text": "Do you ship internationally?",
      "timestamp": "2026-07-19T17:05:51Z",
      "is_read": false,
      "is_replied": false,
      "reaction": null,
      "parent_comment_id": null,
      "sender": {
        "id": "17841400000",
        "name": "Amelia Rivera",
        "username": "amelia.rivera",
        "profile_picture": "https://..."
      },
      "post": null
    }
  ],
  "pagination": { "next_cursor": null, "has_more": false, "limit": 50 }
}
```

`direction` is `incoming` for messages from the other person and `outgoing` for your replies.

### A note on conversation IDs

Conversation IDs are opaque strings. Some, LinkedIn especially, contain characters like `:` and `()` (for example `linkedin_comment_urn:li:activity:7484628878586646528`). Always URL-encode the ID when you place it in a request path. Our SDKs handle this for you.

## Marking a conversation read

Marks every unread incoming message in the conversation as read.

```bash
curl -X POST "https://api.omnisocials.com/v1/inbox/conversations/CONVERSATION_ID/read" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY"
```

Response:

```json
{ "conversation_id": "instagram_17841400000_17841464825884163", "marked_read": 2 }
```

## Replying

Sends a reply in an existing conversation. Works for DMs, comments, and mentions.

```bash
curl -X POST "https://api.omnisocials.com/v1/inbox/conversations/CONVERSATION_ID/reply" \
  -H "Authorization: Bearer $OMNISOCIALS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Yes, we ship worldwide!" }'
```

Response:

```json
{
  "data": {
    "id": "22380029",
    "conversation_id": "instagram_17841400000_17841464825884163",
    "platform": "instagram",
    "type": "dm",
    "direction": "outgoing",
    "text": "Yes, we ship worldwide!",
    "timestamp": "2026-07-19T15:25:03Z",
    "is_read": true,
    "is_replied": false,
    "sender": { "id": "you", "name": "You", "username": "you", "profile_picture": null },
    "post": null
  }
}
```

On Facebook DMs you can attach media by passing `attachment_url` together with `attachment_type` (`image`, `video`, `audio`, or `file`).

### Reply rules

Platform and policy limits apply. Handle these responses:

| Situation | Response |
|-----------|----------|
| The conversation does not exist in this workspace | `404 not_found` |
| Replying to a DM more than 24 hours after the user's last message | `422 outside_messaging_window` |
| The workspace has sent 1,000 replies in the last 24 hours | `429 reply_limit_reached` |
| The key or role lacks inbox access | `403 insufficient_scope` |
| The platform rejected the reply | `502 platform_error` |

You can only reply to conversations that already exist in your inbox. The API cannot start a new conversation: Instagram requires the person to message you first, and cold outreach is against platform policy. Direct-message replies must be sent within the platform's 24-hour messaging window. Each workspace can send up to 1,000 replies per rolling 24 hours; contact robert@omnisocials.com if you need a higher limit.

## Platform notes

| Platform | What is supported |
|----------|-------------------|
| Instagram | DMs, comments, mentions, and story mentions. The person must have messaged you first to open a DM thread. |
| Facebook | Page DMs (Messenger), comments, and mentions. DM replies can include a media attachment. |
| LinkedIn | Company page comments and mentions only. LinkedIn has no DM API, and personal profiles are not supported. Replies post as the organization. |
| TikTok | Coming soon. |

## Using it from an AI assistant

The inbox is available through the OmniSocials MCP server, so you can connect Claude, Cursor, or any MCP client and manage your inbox in natural language. The tools are `list_inbox_conversations`, `get_inbox_conversation`, `mark_inbox_read`, and `reply_to_inbox`. See [MCP Server](/mcp-server).

Every SDK also ships an `inbox` resource. See [SDKs](/sdks).