Social Inbox

Manage inbox conversations, contacts, tags, assignments, and activity reports. Availability depends on workspace permissions and enabled features.

• Readlist_inbox_itemsList Social Inbox items — comments on the agency's posts, direct messages and @mentions — newest first, 20 per page (the result carries pageSize). Filter by kind, platform (facebook, instagram, x, linkedin, youtube, bluesky, mastodon), status (open | resolved), client or keyword. Filters apply before paging: `total` counts only the items matching them, so page 0, 1, 2… until you have `total` items is a complete walk. Every item carries `actions` — what you can do through this API (reply, privateReply, like/unlike, hide/unhide, delete, resolve/reopen, tag, assign) as { ok: true } or { ok: false, reason: network | window | done | deleted, reasonText } — so you know before trying whether a reply is possible and why not, and `appActions`: other things allowed on the item but done only in the app.
• Readget_inbox_itemGet one Social Inbox item and its full thread (the comment with its replies, or the DM conversation), oldest first. The item carries `actions` (what can be done to it now through this API, and if not why: network | window | done | deleted) and `appActions`, same as list_inbox_items.
• Writereply_to_inbox_itemReply to a Social Inbox comment, DM or mention. Posts live to the network under the business's own name — a comment reply is public. The network's length limit applies (e.g. X 280, Instagram 2,200); DMs on Facebook/Instagram only within Meta's 7-day window.
• Writeset_inbox_item_statusResolve or reopen a Social Inbox comment, DM or mention (status resolved | open). Already in that state answers { changed: false } — safe to repeat. A customer's new reply reopens a resolved DM on its own.
• Writeset_inbox_comment_likeLike (liked: true) or unlike (liked: false) a comment as the business's Page/account. Only where the network allows it (Facebook and X comments — see the item's `actions.like`/`unlike`); refused with the reason elsewhere. Already in that state answers { changed: false }.
• Writemoderate_inbox_commentHide, unhide or DELETE a comment on the network (action hide | unhide | delete). Hide keeps it on the network but out of public view and can be undone with unhide; DELETE removes it from the network and can't be undone (the Inbox keeps the row, marked deleted, and resolves it). Only where the network allows it — see the item's `actions.hide`/`unhide`/`delete`; refused with the reason elsewhere. For banning a YouTube commenter use moderate_youtube_comment.
• Writesend_inbox_private_replyAnswer a Facebook or Instagram comment with a private DM to its author (Meta Private Replies). Sends a REAL message under the business's name. Meta allows ONE per comment, within 7 days of it — see the item's `actions.privateReply`; refused with the reason otherwise (including "done" when one was already sent). Up to 1000 characters (not silently cut).
• Writeassign_inbox_itemAssign a Social Inbox comment, DM or mention to a teammate (an agency member — see list_team_members). Adds an owner (an item can have several); re-assigning the same person updates the note and does not notify them again. A new assignee gets an in-app notification. Recorded as assigned by the agent unless a person is behind this session.
• Writeunassign_inbox_itemRemove one owner from a Social Inbox item (pass assigneeUserId), or clear every owner (omit it).
• Readlist_inbox_tagsList the workspace's Social Inbox tags (id, name, colour, archived, how many items carry it) — the vocabulary tag_inbox_item uses. Tags are agency-wide labels created in the app.
• Writetag_inbox_itemAdd and/or remove tags on one Social Inbox item. Name tags by id or by name (from list_inbox_tags); a tag that doesn't exist is refused by name (new tags are created in the app), and an archived tag can't be added.
• Writemoderate_youtube_commentReject a viewer's comment on one of the agency's YouTube videos (hides it on YouTube and resolves it in the Inbox). action "ban" also bans the commenter from the channel. Can't be undone from here.
• Writeedit_youtube_commentEdit the text of the agency's OWN YouTube comment or reply (never someone else's). Up to 10,000 characters.
• Writedelete_youtube_commentDelete the agency's OWN YouTube comment or reply (never someone else's). Permanent on YouTube.
• Writeapply_inbox_actionsResolve/reopen, resolve a whole comment thread, mark read/unread or save/unsave inbox items. Provide exactly one of items (1–2000 kind/id pairs) or a structured filter. Every item must be accessible under user and credential client scope. Thread expansion also checks every owner and refuses more than 2000 items. markRead/markUnread skip DMs and report skipped. Changes inbox state only; never sends a message.
• Writeclassify_inbox_itemsCorrect sentiment, language, intent, needsResponse or spam on inbox items. Provide items or a structured filter and at least one field. Null clears a field. Pins the correction against automatic classification. Checks all selected clients before writes; never invokes the model or sends a message.
• Writetriage_inbox_itemsSet inbox priority (1 critical to 4 low) and/or caseType; null clears a value. Provide items or a structured filter. Checks all selected clients before writes. Returns updated/skipped; changes internal state only.
• Readget_inbox_assigneesRead assignment owners and notes for one accessible inbox item. Returns assignment (first or null) and assignments. Requires active agency Social access and Inbox enabled.
• Readget_inbox_contactRead the author contact profile of an inbox item. Shared across the agency, so requires an unrestricted owner/admin and unrestricted credential. Returns empty profile fields if no saved profile exists, or 404 if the item has no usable identity.
• Writeupdate_inbox_contactUpdate company, occupation, description, email, phone or listIds for an inbox author. Null or empty text clears fields; listIds replaces memberships and [] clears them. Shared profile requires unrestricted owner/admin and credential. Every list must belong to the agency. Never sends a message.
• Readlist_inbox_contact_listsRead agency-wide contact list IDs and names. Requires unrestricted owner/admin and credential because lists span clients.
• Writecreate_inbox_contact_listCreate an agency-wide contact list with a 1–60 character name. A matching name returns the existing list. Requires unrestricted owner/admin and credential.
• Writecreate_inbox_tagCreate an agency-wide inbox tag or restore an archived tag with the same name. Optional color: neutral, accent, success, warning or danger; null clears color. Requires unrestricted owner/admin and credential. This changes shared vocabulary across clients.
• Writeupdate_inbox_tagRename, recolor, archive or restore an agency-wide inbox tag. At least one change required. Archiving preserves existing item links; restore brings them back. Requires unrestricted owner/admin and credential.
• Readget_inbox_activity_reportRead received/actioned counts, action rates and time-to-action by day/hour, including the previous period. Optional clientId and locations are intersected with caller access. Provide both from/to dates at most 366 days apart or omit both for the last 30 days. tz is minutes east of UTC, -840 to 840. Null means unavailable and truncated:true means the item cap was reached. Never collects live provider data.