Unified inbox

The inbox is a unified social inbox API: a single endpoint that returns comments, direct messages, mentions, and reviews from every connected platform in one normalized Interaction shape, so you build inbox logic once instead of per platform. SocialAPI provides a unified inbox API for reading and responding to all inbound engagement across your connected accounts. Comments, DMs, reviews, and mentions are accessed through consistent endpoints with the same response shape regardless of platform. SocialAPI proxies comments, reviews, and mentions live from the platform API, so you always see the latest state. DM conversations and messages are stored in SocialAPI’s database to support threading and pagination.

Comments

List comments across all connected accounts, reply, and moderate.

Endpoints

Method	Path	Description
`GET`	`/v1/inbox/comments`	List posts that received comments across accounts
`GET`	`/v1/inbox/comments/:postId`	List comments on a specific post
`GET`	`/v1/inbox/comments/:postId/:commentId/replies`	List replies to a specific comment
`POST`	`/v1/inbox/comments/:postId`	Reply to a comment on a post
`DELETE`	`/v1/inbox/comments/:postId/:commentId`	Delete a comment
`POST`	`/v1/inbox/comments/:postId/:commentId/hide`	Hide a comment
`DELETE`	`/v1/inbox/comments/:postId/:commentId/hide`	Unhide a comment
`POST`	`/v1/inbox/comments/:postId/:commentId/like`	Like a comment
`DELETE`	`/v1/inbox/comments/:postId/:commentId/like`	Unlike a comment
`POST`	`/v1/inbox/comments/:postId/:commentId/private-reply`	Send a private DM in reply to a comment

:postId accepts a platform post ID (e.g., 17895695668004550). :commentId accepts a SocialAPI interaction ID (sapi_cmt_...). See Interaction IDs for the encoding. Comment likes are supported on Facebook and LinkedIn Page only (see the matrix below); other platforms return 501 with code resource.not_supported. Private replies (Instagram and Facebook) are limited by Meta to one per comment, within 7 days of the comment. On Facebook the commenter’s response continues as a normal Messenger conversation; on Instagram a private reply does not open a standard 24-hour messaging window.

Platform capabilities

Platform	Reply	Hide	Like	Delete	Private reply
Instagram	Yes	Yes	No	Yes	Yes
Facebook	Yes	Yes	Yes	Yes	Yes
Threads	Yes	Conditional	No	Conditional	No
Google	Yes	No	No	No	No
LinkedIn Page	Yes	No	Yes	Yes	No
LinkedIn	Soon	No	No	No	No
YouTube	Yes	Yes	No	Yes	No
X / Twitter	Yes	No	No	No	No
TikTok	No	No	No	No	No

For Threads, Hide is available on comments not owned by the user; Delete is available on own replies. LinkedIn Page (linkedin_page) is the organization page connector and is available in beta. Each comment in the response includes a capabilities object so your code can check what is actually allowed for that specific item.

Example: list and reply

# List posts that have comments
curl https://api.social-api.ai/v1/inbox/comments \
  -H "Authorization: Bearer $SOCAPI_KEY"

# List comments on one post
curl "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a specific comment on a post (postId is the platform post ID)
curl -X POST "https://api.social-api.ai/v1/inbox/comments/17895695668004550" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
    "comment_id": "sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U",
    "text": "Thanks for the feedback!"
  }'

# Hide a comment
curl -X POST "https://api.social-api.ai/v1/inbox/comments/{postId}/{commentId}/hide" \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }'

Direct messages

Read conversations and send messages across platforms that support DMs.

Endpoints

Method	Path	Description
`GET`	`/v1/inbox/conversations`	List DM conversations
`GET`	`/v1/inbox/conversations/:id`	Get a single conversation
`PATCH`	`/v1/inbox/conversations/:id`	Update a conversation (set status to `active` or `archived`)
`POST`	`/v1/inbox/conversations/:id/read`	Mark a conversation as read
`GET`	`/v1/inbox/conversations/:id/messages`	Get messages in a conversation
`POST`	`/v1/inbox/conversations/:id/messages`	Send a message

List conversations query parameters

Parameter	Type	Default	Description
`account_id`	string		Filter by connected account ID
`platform`	string		Filter by platform (e.g., `instagram`, `facebook`)
`status`	string	`active`	Conversation status: `active` or `archived`
`limit`	integer	`25`	Page size (1-100)
`cursor`	string		Pagination cursor from the previous response

Platform support

Platform	DMs supported	Notes
Instagram	Yes	24-hour messaging window for non-followers
Facebook	Yes	Via Messenger Send API, 24-hour response window
LinkedIn	No	Platform API does not expose DMs
TikTok	No	Not available via API
Google	No	Not applicable
Threads	No	Not available via API
YouTube	No	Not available via API

Sending text and attachments

A message can carry text, an attachment, interactive content, or a combination. Provide text, attachment_url, or interactive content (quick_replies, buttons, or cards): at least one is required.

Field	Required	Description
`account_id`	Yes	Connected account that owns the conversation
`text`	Conditional	Message body. Required unless `attachment_url` or interactive content is set
`attachment_url`	Conditional	Publicly reachable URL of a media file to attach. Required unless `text` or interactive content is set
`quick_replies`	No	Tappable reply chips (Instagram, Facebook). See Interactive messages below
`buttons`	No	Button template with 1 to 3 call-to-action buttons (Instagram, Facebook)
`cards`	No	Carousel of cards, each with an image and buttons (Instagram, Facebook)

On Facebook and Instagram, attachment_url is delivered as a Messenger attachment. The attachment type (image, video, audio, or file) is inferred from the URL file extension, so use a direct media link with the correct extension (for example .jpg, .mp4, .mp3). URLs without a recognized media extension are sent as a generic file. The media must be hosted on a publicly reachable URL (max 25 MB); the platform fetches it directly.

Interactive messages

On Instagram and Facebook you can send structured, tappable content alongside or instead of plain text. Set at most one of quick_replies, buttons, or cards per message. When the recipient taps a quick reply or a postback button, you receive a dm.postback webhook carrying the payload you defined, so you can drive automated flows. These features require the recipient to be inside the 24 hour messaging window, the same as any other message. Quick replies render up to 13 tappable chips above the keyboard. They require text and are plain text only.

Field	Required	Description
`quick_replies[].title`	Yes	Chip label (20 characters or fewer)
`quick_replies[].payload`	No	Value echoed back to your webhook when the chip is tapped

Buttons render a text bubble with 1 to 3 call-to-action buttons. They use text as the bubble body (640 characters or fewer).

Field	Required	Description
`buttons[].type`	Yes	`url` (opens a link) or `postback` (sends a `dm.postback` webhook)
`buttons[].title`	Yes	Button label (20 characters or fewer)
`buttons[].url`	Conditional	Destination URL. Required when `type` is `url`
`buttons[].payload`	Conditional	Value echoed back to your webhook. Required when `type` is `postback`

Cards render a horizontally scrollable carousel of up to 10 cards, each with an image, title, subtitle, and up to 3 buttons. (Carousels are not available in the MCP send_dm tool; use the REST endpoint.)

Field	Required	Description
`cards[].title`	Yes	Card title (80 characters or fewer)
`cards[].subtitle`	No	Card subtitle (80 characters or fewer)
`cards[].image_url`	No	Card image URL
`cards[].buttons`	No	Up to 3 buttons, same shape as `buttons` above

Example: list conversations and send a message

# List conversations
curl https://api.social-api.ai/v1/inbox/conversations \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Send a text message in a conversation
curl -X POST https://api.social-api.ai/v1/inbox/conversations/sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_abc123", "text": "Your order has shipped!" }'

# Send an image attachment (text optional)
curl -X POST https://api.social-api.ai/v1/inbox/conversations/sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_abc123", "text": "Here is your receipt", "attachment_url": "https://cdn.example.com/receipt.jpg" }'

# Send quick replies (Instagram, Facebook)
curl -X POST https://api.social-api.ai/v1/inbox/conversations/sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "account_id": "acc_abc123",
        "text": "How can we help?",
        "quick_replies": [
          { "title": "Track my order", "payload": "TRACK_ORDER" },
          { "title": "Talk to support", "payload": "SUPPORT" }
        ]
      }'

# Send a button template (Instagram, Facebook)
curl -X POST https://api.social-api.ai/v1/inbox/conversations/sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/messages \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "account_id": "acc_abc123",
        "text": "Your order has shipped.",
        "buttons": [
          { "type": "url", "title": "Track order", "url": "https://shop.example.com/orders/123" },
          { "type": "postback", "title": "Talk to support", "payload": "SUPPORT" }
        ]
      }'

Manual sync

Conversations and messages are normally refreshed on a staleness window: a read that finds stale data syncs before serving it. Use /v1/inbox/sync when you want to trigger a refresh independently of a read, for example to warm a thread before opening it. There are two targets. With only account_id, the job refreshes that account’s conversation list, not every thread’s messages: refreshing 200 threads on one button press is a rate-limit incident waiting to happen, so a list sync stays scoped to the list. Add conversation_id to instead refresh one thread’s messages.

Method	Path	Description
`POST`	`/v1/inbox/sync`	Start a sync for an account’s conversation list, or one thread
`GET`	`/v1/inbox/sync`	Get the current sync state for a target

POST body

Field	Required	Description
`account_id`	Yes	Connected account to sync
`conversation_id`	No	Thread to sync instead of the conversation list

GET query parameters

Parameter	Required	Description
`account_id`	Yes	Connected account to check
`conversation_id`	No	Thread to check instead of the conversation list

Response

Field	Description
`state`	`idle`, `syncing`, or `failed`
`started_at`	When the current or most recent job started
`finished_at`	When the current or most recent job finished (null while syncing)
`last_synced_at`	When this target last completed a sync. GET only: a POST response is the job that just started, so the value worth reading is the one you poll back
`error`	Error message if the last job failed
`synced`	Count from the last completed job: conversations upserted for a list sync, messages inserted for a thread sync. Display only

POST returns immediately (202) with the job’s starting state. Calling it again for the same target while a job is already running returns that running job rather than starting a second one. Rate limit. Each target accepts one forced sync every 5 minutes. A second attempt inside that window returns 429 with a Retry-After header carrying the seconds to wait, and the error code inbox.sync_rate_limited. Wait that long rather than retrying sooner: the limit exists because the platforms have their own, stricter limits, and burning them affects every sync for that account. The limit applies only to syncs you trigger. Ordinary reads of the inbox refresh data on their own schedule and never consume it, so opening the inbox does not make the next manual refresh fail. A sync that is already running is not rate-limited: polling POST for a target you are already waiting on returns that job’s state rather than a 429. The poll pattern is: POST /v1/inbox/sync, then poll GET /v1/inbox/sync until state is no longer syncing, then refetch the conversation or message list. If you want a fast cold open on a slow platform (Instagram in particular), sync the thread first and read it once it is warm, rather than opening it cold: the read path still blocks on a cold open, so reading first gets you the same wait either way. GET /v1/inbox/conversations and GET /v1/inbox/conversations/:id/messages also return sync_state and last_synced_at on the list response itself, so a client already polling those lists can watch sync state without a separate call to /v1/inbox/sync. Both fields are additive: a client that ignores them sees exactly the response it saw before.

# Start a conversation-list sync
curl -X POST https://api.social-api.ai/v1/inbox/sync \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J" }'

# Start a sync for one thread
curl -X POST https://api.social-api.ai/v1/inbox/sync \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "conversation_id": "sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U" }'

# Poll status for the thread
curl "https://api.social-api.ai/v1/inbox/sync?account_id=acc_01HZ9X3Q4R5M6N7P8V2K0W1J&conversation_id=sapi_dm_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U" \
  -H "Authorization: Bearer $SOCAPI_KEY"

Reviews

Read and reply to reviews on platforms that support them.

Endpoints

Method	Path	Description
`GET`	`/v1/inbox/reviews`	List reviews
`POST`	`/v1/inbox/reviews/:id/reply`	Reply to a review

Platform support

Platform	Reviews
Google	Yes (Google Business Profile)
All others	No

Example

# List reviews
curl https://api.social-api.ai/v1/inbox/reviews \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a review
curl -X POST https://api.social-api.ai/v1/inbox/reviews/sapi_rev_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U/reply \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J", "text": "Thank you for the review!" }'

Mentions

Read mentions of a connected account, and reply to them as a public comment.

Endpoints

Method	Path	Description
`GET`	`/v1/accounts/:id/mentions`	List mentions for a connected account
`POST`	`/v1/accounts/:id/mentions/reply`	Reply to a mention as a public comment

Mentions are scoped to a single connected account, not the workspace. Replying works even when the mention is on someone else’s post, where the normal comment-reply endpoint is not allowed. Pass media_id (the post the mention is on, or the sapi_mnt_ id from the list response) and text. Set comment_id only when the mention was inside a comment; omit it to reply to a mention in the post caption. A reply consumes 1 interaction credit.

Platform support

Platform	List mentions	Reply to mention
Instagram	Yes	Yes
Facebook	Yes	Yes
X / Twitter	Yes	No
All others	No	No

Example

# List mentions
curl "https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions" \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a comment mention as a public comment
curl -X POST https://api.social-api.ai/v1/accounts/acc_01HZ9X3Q4R5M6N7P8V2K0W1J/mentions/reply \
  -H "Authorization: Bearer $SOCAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "17895695668004550", "comment_id": "17858893269577012", "text": "Thanks for the shout-out!"}'

Interaction IDs

Every interaction returned by the inbox has a stable ID with a type prefix:

Prefix	Type
`sapi_cmt_`	Comment
`sapi_dm_`	DM
`sapi_rev_`	Review
`sapi_mnt_`	Mention

The suffix encodes the platform and the platform-native ID, so you can route actions without a database lookup. See Interaction IDs for the full encoding scheme.

Webhooks

SocialAPI can notify your server when new inbound interactions arrive (new comment, new DM, new review). Register a webhook endpoint and subscribe to the event types you care about. See Webhooks for setup and event reference.

Platform support for the full capability matrix
Interaction IDs for the ID encoding scheme
Webhooks for real-time event delivery
API Reference for complete endpoint schemas

Getting Started

Core Concepts

Comments

Endpoints

Platform capabilities

Example: list and reply

Direct messages

Endpoints

List conversations query parameters

Platform support

Sending text and attachments

Interactive messages

Example: list conversations and send a message

Manual sync

Reviews

Endpoints

Platform support

Example

Mentions

Endpoints

Platform support

Example

Interaction IDs

Webhooks

​Comments

​Endpoints

​Platform capabilities

​Example: list and reply

​Direct messages

​Endpoints

​List conversations query parameters

​Platform support

​Sending text and attachments

​Interactive messages

​Example: list conversations and send a message

​Manual sync

​Reviews

​Endpoints

​Platform support

​Example

​Mentions

​Endpoints

​Platform support

​Example

​Interaction IDs

​Webhooks

​Related

Comments

Endpoints

Platform capabilities

Example: list and reply

Direct messages

Endpoints

List conversations query parameters

Platform support

Sending text and attachments

Interactive messages

Example: list conversations and send a message

Manual sync

Reviews

Endpoints

Platform support

Example

Mentions

Endpoints

Platform support

Example

Interaction IDs

Webhooks

Related