Copy page

Guides

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.

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

Response:

Code
{
  "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:

Code
"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).

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

Response:

Code
{
  "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.

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

Response:

Code
{ "conversation_id": "instagram_17841400000_17841464825884163", "marked_read": 2 }

Replying

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

Code
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:

Code
{
  "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 [email protected] 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.

Every SDK also ships an inbox resource. See SDKs.