Social inbox API: DMs, comments and mentions
Read and reply to your Instagram and Facebook DMs, comments, and mentions, LinkedIn company-page comments and mentions, TikTok and YouTube video comments, and Threads replies 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.
There is also a work queue, GET /inbox/next, that hands you the next thing that needs an answer together with its conversation and post, and comment moderation (hide, delete) on the platforms that allow it. See Working through the inbox and Hiding and deleting comments.
X (Twitter) DMs are also available as a per-workspace opt-in, see X direct messages. Threads replies and mentions are covered too, see Threads replies and mentions.
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, read messages, and pull the next unanswered item |
inbox:write | Mark conversations read, send replies, hide and delete comments |
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.
Terminal
Response:
JSON
Query parameters (all optional):
| Parameter | Description |
|---|---|
platform | instagram, facebook, linkedin, tiktok, youtube, x, or threads |
type | dm, comment, or mention |
unread | true returns only conversations with unread incoming messages |
unanswered | true returns only conversations that still need an answer: the person's latest DM has no reply after it (Instagram and Facebook DMs past the 24-hour messaging window included: they cannot be answered through the API, but the person is still waiting), or a comment or mention has not been replied to and is not hidden. Replies sent from the native apps count as answers. Read state is ignored here; use GET /inbox/next for a work queue. See What counts as unanswered |
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. See Post context on comments.
Cursor pagination
The inbox list endpoints use cursor pagination, not offset. Every response carries a pagination object:
JSON
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).
Terminal
Response:
JSON
direction is incoming for messages from the other person and outgoing for your replies. Replies sent from the platform's own app show up as outgoing too, see Replies sent from the native apps.
permalink links to the reply or mentioning post on the platform when one is known, null otherwise. hidden is set on comments and mentions: true when the comment is hidden on the platform (see Hiding and deleting comments), false when it is visible. It is null on DMs.
Media on a message
attachment is set on messages that carry media, and null otherwise. It carries url and type (image, video, audio, or file):
JSON
This applies to inbound Instagram and Facebook DM photos, videos, voice messages, and Instagram story mentions, and to any reply you sent with attachment_url. Instagram/Facebook's own attachment URL is short-lived (it typically stops resolving within hours); we download it once when the message arrives and re-host it on our own CDN, so attachment.url keeps working indefinitely.
type reflects the fetched bytes, not the platform's label: a photo the platform sent under an unlabelled attachment type is image, and a story mention that is really an MP4 is video. type: "file" means we fetched the media but could not classify it (treat it as an opaque download). type: "link" means the platform's URL did not point at media, for example a shared post that resolves to an instagram.com page; url is then the platform's own link, not re-hosted, and may require login or expire.
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.
Post context on comments
Comment and mention conversations carry the post they belong to, on the conversation and on every message in it, so a reply can be drafted with the post in view: "what size is this?" needs the caption and the picture. DMs have post: null.
JSON
| Field | Description |
|---|---|
id | The platform's id of the post |
caption | The post text, when known |
thumbnail | Image URL of the post, or the video's cover |
url | Public link to the post on Instagram, Facebook, YouTube, TikTok, LinkedIn, or Threads, when the platform provides one. null otherwise |
media_type | The platform's own label for the post, for example IMAGE, VIDEO, or CAROUSEL_ALBUM on Instagram, when known. null otherwise |
Instagram stores the link and media type when the comment arrives. Instagram conversations that reached the inbox before September 6, 2026 get url and media_type filled in the first time you read them through the API.
Marking a conversation read
Marks every unread incoming message in the conversation as read.
Terminal
Response:
JSON
Marking read also takes the conversation out of the work queue for good, so this is how you skip an item you do not want to answer.
Replying
Sends a reply in an existing conversation. Works for DMs, comments, and mentions. The reply text caps at 2,000 characters (150 on TikTok comments); longer text returns 400 validation_error.
Terminal
Response:
JSON
On Facebook and Instagram DMs you can attach media by passing attachment_url together with attachment_type (image, video, audio, or file). text is optional when attachment_url is set: an attachment-only reply is allowed. Other platforms are text-only; attachment_url is ignored there.
Replying to a specific comment
Every comment on a post shares one conversation. Pass message_id, the inbox id of the specific incoming comment or mention you are answering (message.id from GET /inbox/next, or a message id from Reading a conversation), so the reply lands under that comment. Without it the reply is posted under the newest incoming comment on the post, which may be a different person than the one you drafted for. Always pass it when replying to an item served by the queue. It is ignored for DMs: a DM reply goes to the conversation. The outgoing message's parent_comment_id is the platform id of the comment you answered.
Terminal
A message_id that is not an incoming message of this conversation returns 404 not_found; one that is not numeric returns 400 validation_error.
Chaining to the next item
Pass include_next: true in the body and the response also carries next, the next conversation that needs an answer (same shape as GET /inbox/next, with its default order and filters), and remaining, the number of unanswered items still waiting after it. This saves the extra call when you are working through the inbox.
Terminal
JSON
next is null and remaining is 0 when nothing is waiting. The reply itself is never affected: if the queue lookup fails, the reply still goes out and next comes back null.
Reply rules
Platform and policy limits apply. Handle these responses:
| Situation | Response |
|---|---|
| The conversation does not exist in this workspace | 404 not_found |
message_id is not an incoming message of this conversation | 404 not_found |
message_id is not numeric | 400 validation_error |
| The comment or message you reply to was deleted, hidden, or restricted on the platform | 404 not_found |
text is longer than the platform allows (2,000 overall, 1,000 on Instagram DMs, 150 on TikTok comments) | 400 validation_error |
Replying to an Instagram or Facebook DM more than 24 hours after the person's last message (Meta policy). Checked before the send, so nothing goes out; the message names when the window closed, and GET /inbox/next reports the same in reply_window | 422 outside_messaging_window (answer that DM from the Instagram or Facebook app, which is mirrored into the inbox, or mark the conversation read to skip it; do not retry) |
| The same reply (same text and attachment) already went out to this comment or DM conversation in the last 10 minutes, or is being sent right now | 409 duplicate_reply (nothing was sent again; data carries the earlier message) |
The platform refuses replies to this item for good: Facebook #1705 (the comment sits on a share or boosted copy of the post, or the commenter restricts replies), or a YouTube thread whose canReply is false (comments are off on the video, or the comment was removed or held for review) | 422 reply_not_allowed (the item is dropped from GET /inbox/next; do not retry) |
| 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 |
| The connection lost a needed permission (TikTok comments, LinkedIn, or the Threads reply permission) | 401 reauth_required |
| 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 (it turns back on by itself after a top-up) | 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.
Working through the inbox
GET /inbox/next is a work queue. It returns the one item that should be answered next, together with the conversation so far and the post it belongs to, so you can draft a reply from a single call.
Items are served in this order:
- DMs that can still be answered: Instagram and Facebook DMs inside Meta's 24-hour messaging window, the one whose window closes soonest first, and X DMs, which have no window.
- Instagram and Facebook DMs whose 24-hour window has closed. They are served with
reply_window.open = false: the API cannot reply to them, but the person is still waiting. Answer them from the Instagram or Facebook app (that reply is mirrored into the inbox and clears the item), or mark the conversation read to skip it. - Comments and mentions, oldest first.
order=newest reverses the order within each group.
Terminal
Response:
JSON
messageis the unanswered incoming message itself: the person's latest DM, or the specific comment. Itsconversation_idis what the reply endpoint takes, and itsidis themessage_idto pass along with the reply for comment threads, so the reply lands under this comment and not under the newest one on the post. The sameidis what the hide and delete endpoints take.messagesis the conversation so far, oldest first (the most recent 50 messages for long DM threads).reply_windowsays whether a reply can still be sent through the API. Only Instagram and Facebook DMs have a window (closes_atis the person's last message plus 24 hours); every other item hasopen: trueandcloses_at: null. Whenopenisfalsethe item is still served, because the person is still waiting, but the reply endpoint answers422 outside_messaging_window: answer it from the native app or mark the conversation read.remainingis how many unanswered items are still waiting after this one, capped at 500.dataisnullandremainingis0when the queue is empty.
What counts as unanswered
- A DM needs an answer when the person's latest message has no reply after it. Instagram and Facebook DMs past Meta's 24-hour messaging window are included too, flagged with
reply_window.open = false: the API cannot reply to them, but the person is still waiting. - A comment or mention needs an answer when nobody replied to it and it is not hidden.
- Replies sent from the native apps count as answers (see Replies sent from the native apps), so a thread a colleague answered on their phone is not served again.
- Instagram mentions are skipped, there is no reply path for them.
- The queue looks at the last 30 days of activity.
The same rules power the unanswered=true filter on GET /inbox/conversations, which lists everything waiting at once rather than serving one item at a time. The list filter ignores read state; the queue serves unread items only by default.
Skipping an item
Only unread items are served by default, so marking a conversation read (POST /inbox/conversations/{id}/read) is the durable skip: the item drops out of the queue and stays out. Pass include_read=true to also serve items that were marked read but never answered, for example for an end-of-day sweep. For a temporary skip within one session, pass exclude with a comma-separated list of conversation ids (up to 100); those are left out of that call only.
Query parameters
All optional.
| Parameter | Description |
|---|---|
platform | Only items from one platform: instagram, facebook, linkedin, tiktok, youtube, x, or threads |
type | Only items of one type: dm, comment, or mention |
order | oldest (default) serves the item that has waited longest first; newest serves the most recent first. Both apply within each group: answerable DMs still come before expired Instagram and Facebook DMs, which come before comments and mentions |
include_read | true also serves items that were marked read but never answered |
exclude | Comma-separated conversation ids to leave out of this call, up to 100 |
An unknown platform, type, or order returns 400 validation_error.
The loop
- Call
GET /inbox/next. - Draft a reply from
data.message,data.messages, anddata.conversation.post. Ifdata.reply_window.openisfalse, skip the draft: answer that DM from the Instagram or Facebook app, or mark the conversation read, then callGET /inbox/nextagain. - Send it with
POST /inbox/conversations/{conversation_id}/reply, passingmessage.idasmessage_id(so a comment reply lands under the served comment, not under the newest one on the post) andinclude_next: true. The response carries the sent reply plusnextandremaining. - Repeat from step 2 with
nextuntil it isnull.
To skip an item, mark it read (for good) or add it to exclude (this session only). To deal with spam, hide or delete it; a hidden comment no longer counts as unanswered.
Hiding and deleting comments
Comments people leave on your posts can be moderated from the API, as the post owner. Both endpoints take the message id from the conversation messages list or from GET /inbox/next, not the conversation id, and need the inbox:write scope (API keys) or the access_social_inbox permission (OAuth/MCP).
| Platform | Hide | Delete |
|---|---|---|
| Yes | Yes | |
| Yes | Yes | |
| TikTok | Yes | Yes |
| YouTube | Yes, through YouTube's moderation status | No. YouTube's API does not let a channel delete other people's comments; hide instead |
| Threads | Yes, top-level replies on your posts only | No |
| No | No |
Hiding a comment
Terminal
The body is optional; hide defaults to true, and { "hide": false } unhides. The response returns the updated message under data with hidden flipped. The comment keeps its place in the conversation, disappears from public view on the platform until you unhide it, and no longer counts as unanswered.
On YouTube, hiding sets the comment's moderation status to rejected, which removes the comment and its replies from public view; unhiding publishes it again. On Threads, only incoming top-level replies can be hidden; Threads does not allow hiding nested replies. On Instagram, the API reads the comment back after the call and reports Instagram's own hidden state, so hidden on the returned message is what Instagram actually shows. When Instagram accepted the call but still reports the old state, the response is 502 hide_not_applied and the inbox is left unchanged.
| Situation | Response |
|---|---|
| The message is not an incoming comment on a platform that supports hiding | 400 unsupported_platform |
| The Threads reply is nested, or Threads refused | 400 not_hideable |
| The Threads reply permission or the TikTok comments authorization is missing or expired | 401 reauth_required |
The account was connected without the comment-moderation permission (Facebook pages_manage_engagement, Instagram instagram_business_manage_comments); reconnect it under Settings -> Organisation -> Workspaces | 403 reconnect_required |
| The message does not exist in this workspace | 404 not_found |
| No matching account connected to the workspace | 404 account_not_connected |
| Facebook does not let the Page hide (or unhide) this particular comment: the commenter blocked the Page, their account is deactivated or restricted, or the comment sits on a shared copy of the post | 422 cannot_hide (retrying does not change it; handle it in Facebook, or mark the conversation read to skip it) |
| Instagram accepted the hide (or unhide) but still reports the comment in the old state when read back. This happens with comments Instagram shows under "Comments from Facebook" on a reel that is also shared to Facebook: they live on Facebook, and Instagram's hide does not reach them | 502 hide_not_applied (the inbox is left unchanged; hide it in the Instagram or Facebook app, do not retry) |
| YouTube's daily API quota is used up; retry after midnight Pacific | 429 quota_exceeded |
| The platform rejected the call | 502 platform_error |
Deleting a comment
Deletes the comment on the platform and from the inbox. Facebook, Instagram, and TikTok comments only. This cannot be undone.
Terminal
Response:
JSON
Replies under the deleted comment go with it: the platforms cascade the delete and the inbox mirrors that, and their inbox ids come back in removed_reply_ids. A comment that is already gone on the platform is still removed from the inbox.
| Situation | Response |
|---|---|
| The message is not an incoming Facebook, Instagram, or TikTok comment | 400 unsupported_platform |
| The TikTok comments authorization expired | 401 reauth_required |
| The account was connected without the comment-moderation permission; reconnect it under Settings -> Organisation -> Workspaces | 403 reconnect_required |
| The message does not exist in this workspace | 404 not_found |
| No matching account connected to the workspace | 404 account_not_connected |
| The platform rejected the call | 502 platform_error |
Replies sent from the native apps
Replies you or a colleague send from the platform's own app are mirrored into the inbox as outgoing messages, so the thread in OmniSocials is complete and the person's message counts as answered. This covers Instagram DMs sent from the Instagram app, Messenger replies sent from Messenger, Meta Business Suite, or another tool, and comment replies posted natively on Instagram and Facebook. The mirrored reply marks the person's message as replied, which also takes it out of the work queue and the unanswered filter.
Facebook Pages connected before September 6, 2026 need a one-time reconnect under Settings -> Organisation -> Workspaces to start receiving Messenger replies sent from the native apps, because the Page's webhook subscription gained a new field (or contact support to have it switched on without a reconnect). Instagram works without a reconnect.
Platform notes
| Platform | What is supported |
|---|---|
| DMs, comments, mentions, and story mentions. The person must have messaged you first to open a DM thread. DM replies can include a media attachment. Comments can be hidden and deleted. Replies sent from the Instagram app are mirrored into the inbox. | |
| Page DMs (Messenger), comments, and mentions. DM replies can include a media attachment. Comments can be hidden and deleted, and liked in the app (not through the API). Replies sent from Messenger or Business Suite are mirrored into the inbox (Pages connected before September 6, 2026 need a reconnect). | |
| Company page comments and mentions only. LinkedIn has no DM API, and personal profiles are not supported. Replies post as the organization, text only. Comments can be liked as the Page in the app (not through the API). No hide or delete. Commenters show as "LinkedIn Member", because LinkedIn does not share their names. | |
| TikTok | Video comments only, after comments are enabled on the TikTok channel. Replies are text only, 150 characters max, and TikTok holds fresh comments and replies in spam review for roughly 15 to 20 minutes. Comments can be hidden and deleted. See TikTok comments. |
| YouTube | Video comments only, YouTube has no DMs. Conversations group per video, and replies are supported. Comments can be hidden through YouTube's moderation status, but not deleted. YouTube has no comment webhooks, so OmniSocials checks each channel for new comments once per day; a new comment can take up to a day to reach the inbox. The standard YouTube connection already covers comments, no extra authorization needed. |
| X (Twitter) | DMs only, after the workspace opts in. Uses credits. DMs can be answered by an automation. See X direct messages. |
| Threads | Replies people leave on your posts, and mentions. Replies publish as native Threads replies, and top-level replies on your posts can be hidden. See Threads replies and mentions. |
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 (purchased at €0.01 per credit), 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
When the balance drops to 50 credits, the person who enabled X DMs and the organisation owner get one notice in the app and one email a day: X DMs pause soon.
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, automations on X stop answering, and the person who enabled X DMs gets an email. After a top-up or an auto-refill, X DMs turn back on by themselves and the person who enabled them gets a notice in the app; there is no switch to flip. 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.
Encrypted chats
X does not give apps the messages of a conversation that runs in its encrypted X Chat. Those messages stay in the X app and never reach the Social Inbox or the API. Unencrypted DMs, such as a first message from someone who does not follow you, still arrive.
TikTok comments
TikTok comments need their own authorization on top of the regular TikTok connection, so they are off until you enable them per channel.
Turning it on
In the app, go to Settings -> Organisation -> Workspaces and press Enable comments on the TikTok channel card. It runs a second TikTok authorization for the comment permissions. From then on, new comments on your videos land in the inbox in real time.
Comments only
TikTok conversations are always type comment: DMs and mentions on TikTok are not part of the inbox. Commenter names and avatars can briefly show as "TikTok User" until TikTok releases the commenter's identity. You can also like and unlike comments from the inbox in the app; liking is not available through the API yet. Comments can be hidden and deleted through the API, see Hiding and deleting comments.
Reply rules
Replies post from the connected TikTok account and are text only, capped at 150 characters. A longer reply, or one with an attachment, returns 400 validation_error. If the comments authorization expires, replies return 401 reauth_required; press Enable comments on the channel card again to fix it.
Spam review delay
TikTok holds fresh comments and replies in spam review for roughly 15 to 20 minutes before they are publicly visible on TikTok. A reply that is accepted by the API will appear under the video, just not immediately.
Threads replies and mentions
Reconnect once. The Threads inbox needs the Threads reply permissions. Threads accounts connected before these permissions were added need a one-time reconnect under Settings -> Organisation -> Workspaces; until then Threads conversations do not appear and Threads replies and hides answer 401 reauth_required.
Threads brings two conversation types into the inbox:
- Replies on your posts (
type: "comment"): every reply someone leaves under one of your Threads posts. Conversations group per root post (conversation_id=threads_comment_<postId>). - Mentions (
type: "mention"): posts that mention your Threads profile (conversation_id=threads_mention_<postId>).
Threads has no DM API, so there are no Threads conversations of type dm.
Reply rules
Replying to a Threads conversation publishes a native Threads reply from your connected account: under the person's reply on your post, or under the post that mentioned you. Replies are text only. If the Threads connection is missing the reply permission (connections made before the permission was added), replies return 401 reauth_required; reconnect Threads under Settings -> Organisation -> Workspaces to fix it.
Hiding a reply
As the post owner, you can hide (or unhide) a reply someone left on one of your Threads posts with the same POST /inbox/messages/{id}/hide endpoint described under Hiding and deleting comments. Threads specifics: only incoming top-level replies can be hidden (a nested reply returns 400 not_hideable), a missing reply permission returns 401 reauth_required, and there is no delete for Threads.
Using it from an AI assistant
The inbox is available through the OmniSocials MCP server, so you can connect Claude, ChatGPT, Cursor, or any MCP client and manage your inbox in natural language. The tools are:
| Tool | What it does |
|---|---|
list_inbox_conversations | List conversations; accepts platform, type, unread, and unanswered |
get_inbox_conversation | Read a thread with the post it belongs to (caption, link, image); every message shows its #id, which the hide and delete tools take |
get_next_unanswered | The work queue: the next item that needs an answer, with the thread and the post, in one call. Accepts platform, type, order, include_read, and exclude |
mark_inbox_read | Mark a conversation read, which also skips it in the queue for good |
reply_to_inbox | Send a reply; pass include_next: true to get the next unanswered item back in the same call |
hide_inbox_comment | Hide or unhide a comment on Instagram, Facebook, TikTok, YouTube, or Threads |
delete_inbox_comment | Delete an Instagram, Facebook, or TikTok comment, with its replies. Irreversible, so the assistant confirms first |
Ask for "work through my unanswered comments" and the assistant runs the loop from Working through the inbox: get_next_unanswered, draft a reply with the post in view, reply_to_inbox with include_next: true, repeat until nothing is waiting. See MCP Server, Claude, and ChatGPT.
Every SDK also ships an inbox resource. See SDKs.