Social Inbox API: DMs, Comments, Mentions

Guides

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.

X (Twitter) DMs are also available as a per-workspace opt-in, see X direct messages. 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`, `linkedin`, or `x`
`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`
An X DM reply, but the credit balance cannot cover it	`402 insufficient_credits`
The workspace's X inbox is paused because credits ran out	`402 x_inbox_suspended`

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.
X (Twitter)	DMs only, after the workspace opts in. Uses credits. See X direct messages.
TikTok	Coming soon.

X direct messages

X DMs work differently from the other platforms because X charges for its DM API. They are off by default, and each workspace opts in separately.

Turning it on

In the app, open the Social Inbox and use the X DMs card. Enabling requires:

An X account connected to the workspace, with DM permissions on the connection. Accounts connected before DM support shipped need a quick reconnect first; the card tells you when that is the case.
The billing permission, since X DMs spend your organisation's credits.
A credit balance of at least 25 credits.

What it costs

X bills its DM API per use. We pass those rates through as credits (1 credit = $0.01), rounded up to whole credits:

Action	Cost
DM received	1 credit ($0.010, X's delivery rate)
DM reply sent	2 credits (covers X's $0.015 send fee)

A reply that fails to send is refunded automatically.

Running out of credits

If the balance hits zero, the X inbox pauses itself: the message that used the last credit still lands in your inbox, but new DMs stop arriving and the person who enabled X DMs gets an email. Top up and re-enable X DMs to resume. DMs sent to you while paused are not recovered.

No history, DMs only

The inbox receives DMs from the moment you enable it. Conversations from before you enabled are not imported, and neither are messages that arrived while the inbox was paused. X conversations are always type dm: comments and mentions on X are not part of the inbox, and replies are DM replies only.

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.

Last modified on August 5, 2026

Media Platforms

Guides

X (Twitter) DMs are also available as a per-workspace opt-in, see X direct messages. 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`, `linkedin`, or `x`
`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

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`
An X DM reply, but the credit balance cannot cover it	`402 insufficient_credits`
The workspace's X inbox is paused because credits ran out	`402 x_inbox_suspended`

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.
X (Twitter)	DMs only, after the workspace opts in. Uses credits. See X direct messages.
TikTok	Coming soon.

X direct messages

X DMs work differently from the other platforms because X charges for its DM API. They are off by default, and each workspace opts in separately.

Turning it on

In the app, open the Social Inbox and use the X DMs card. Enabling requires:

An X account connected to the workspace, with DM permissions on the connection. Accounts connected before DM support shipped need a quick reconnect first; the card tells you when that is the case.
The billing permission, since X DMs spend your organisation's credits.
A credit balance of at least 25 credits.

What it costs

X bills its DM API per use. We pass those rates through as credits (1 credit = $0.01), rounded up to whole credits:

Action	Cost
DM received	1 credit ($0.010, X's delivery rate)
DM reply sent	2 credits (covers X's $0.015 send fee)

A reply that fails to send is refunded automatically.

Running out of credits

No history, DMs only

Using it from an AI assistant

Every SDK also ships an inbox resource. See SDKs.

Last modified on August 5, 2026

Media Platforms