Skip to main content
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 never stores interaction content in its database. Every inbox call proxies live data from the platform API, so you always see the latest state.

​
Comments

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

​
Endpoints

MethodPathDescription
GET/v1/inbox/commentsList posts that received comments across accounts
GET/v1/inbox/comments/:postIdList comments on a specific post
GET/v1/inbox/comments/:postId/:commentId/repliesList replies to a specific comment
POST/v1/inbox/comments/:postIdReply to a comment on a post
DELETE/v1/inbox/comments/:postId/:commentIdDelete a comment
POST/v1/inbox/comments/:postId/:commentId/hideHide a comment
DELETE/v1/inbox/comments/:postId/:commentId/hideUnhide a comment
POST/v1/inbox/comments/:postId/:commentId/likeLike a comment
DELETE/v1/inbox/comments/:postId/:commentId/likeUnlike a comment
POST/v1/inbox/comments/:postId/:commentId/private-replySend a private DM in reply to a comment
:postId and :commentId accept SocialAPI interaction IDs (sapi_cmt_...). See Interaction IDs for the encoding.

​
Platform capabilities

PlatformReplyHideLikeDeletePrivate reply
InstagramYesYesNoYesYes
FacebookYesYesYesYesYes
ThreadsYesConditionalNoConditionalNo
GoogleYesNoNoNoNo
LinkedInSoonNoSoonSoonNo
YouTubeYesYesNoYesNo
X / TwitterYesYesNoConditionalNo
TikTokNoNoNoNoNo
For Threads, Hide is available on comments not owned by the user; Delete is available on own replies. For X / Twitter, Delete is available on own posts. 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/sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U" \
  -H "Authorization: Bearer $SOCAPI_KEY"

# Reply to a comment on that post
curl -X POST "https://api.social-api.ai/v1/inbox/comments/sapi_cmt_GXRM4BNTW7KFYSD3HAEV6QJZ2CLP9U" \
  -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

MethodPathDescription
GET/v1/inbox/conversationsList DM conversations
GET/v1/inbox/conversations/:id/messagesGet messages in a conversation
POST/v1/inbox/conversations/:id/messagesSend a message

​
Platform support

PlatformDMs supportedNotes
InstagramYes24-hour messaging window for non-followers
FacebookYesVia Messenger Send API, 24-hour response window
LinkedInNoPlatform API does not expose DMs
TikTokNoNot available via API
GoogleNoNot applicable
ThreadsNoNot available via API
YouTubeNoNot available via API

​
Sending text and attachments

A message can carry text, an attachment, or both. Provide text, attachment_url, or both: at least one is required.
FieldRequiredDescription
account_idYesConnected account that owns the conversation
textConditionalMessage body. Required unless attachment_url is set
attachment_urlConditionalPublicly reachable URL of a media file to attach. Required unless text is set
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.

​
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" }'

​
Reviews

Read and reply to reviews on platforms that support them.

​
Endpoints

MethodPathDescription
GET/v1/inbox/reviewsList reviews
POST/v1/inbox/reviews/:id/replyReply to a review

​
Platform support

PlatformReviews
GoogleYes (Google Business Profile)
All othersNo

​
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 '{ "text": "Thank you for the review!" }'

​
Mentions

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

​
Endpoints

MethodPathDescription
GET/v1/accounts/:id/mentionsList mentions for a connected account
POST/v1/accounts/:id/mentions/replyReply 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

PlatformList mentionsReply to mention
InstagramYesYes
FacebookYesYes
X / TwitterYesNo
All othersNoNo

​
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:
PrefixType
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.