Inbox
The inbox surface exposes the unified comment + DM stream from your connected Instagram, Facebook, YouTube, Threads and LinkedIn Company Page accounts, plus Bluesky and Mastodon replies and mentions, Telegram channel comments and Google Business Profile reviews. Every endpoint below acts on the workspace the token is pinned to.
Data is cached. Reads serve rows that ShortSync persisted at the last sync. Call POST /inbox/sync (or the ?sync=1 flag on the messages endpoint) when you need fresh data — the platform APIs count against Meta and YouTube's rate limits, so we don't hit them on every read.
Feature flag. The inbox is generally available for comment threads on all connected IG/FB/YouTube accounts. DM threads (Instagram + Facebook Messenger) require Meta's messaging scopes on the connection — see the has_messaging_scope flag on GET /inbox/connections.
Base path: https://api.shortsync.app/v1
| Endpoint | Method | Path | Scope | Purpose |
|---|---|---|---|---|
| List connections | GET | /inbox/connections | inbox:read | Which platform accounts are wired into the inbox |
| List conversations | GET | /inbox/conversations | inbox:read | Filtered + paginated thread list |
| Get messages | GET | /inbox/conversations/{id}/messages | inbox:read | One conversation's full message history |
| Sync inbox | POST | /inbox/sync | inbox:write | Pull fresh threads + messages from every connection |
| Reply | POST | /inbox/conversations/{id}/reply | inbox:write | Post a reply to a comment thread or DM |
| Like a conversation | POST | /inbox/conversations/{id}/like | inbox:write | Like/unlike a top-level comment thread (Instagram, Facebook, LinkedIn) |
| Like a message | POST | /inbox/messages/{id}/like | inbox:write | Like/unlike a nested comment reply (Instagram, Facebook, LinkedIn) |
| Mark conversations seen | POST | /inbox/conversations/mark-seen | inbox:write | Batch mark rows as read for the workspace |
| Mark conversations spam | POST | /inbox/conversations/mark-spam | inbox:write | Bulk flip the local spam moderation flag |
| Load more comments | POST | /inbox/media/load-more | inbox:write | Paginate deeper into a specific video/post's comment history |
| List saved replies | GET | /inbox/saved-replies | inbox:read | The workspace's reusable reply text |
| Create a saved reply | POST | /inbox/saved-replies | inbox:write | Add a saved reply for the whole workspace |
| Update a saved reply | PATCH | /inbox/saved-replies/{id} | inbox:write | Change a saved reply's name or content |
| Delete a saved reply | DELETE | /inbox/saved-replies/{id} | inbox:write | Remove a saved reply |
List connections
/inbox/connections·inbox:readReturns the workspace's platform connections wired into the DM inbox, with per-connection capability flags so you can gate the reply / like / DM actions in your UI before making a call that would fail.
Example request
curl https://api.shortsync.app/v1/inbox/connections \
-H "Authorization: Bearer $TOKEN"Example response
{
"data": [
{
"id": "df1e4cb2-f5d1-4d86-821f-7fd99b2f5c7a",
"platform": "youtube",
"username": "testaccount_shortsyncing",
"avatar_url": "https://yt3.ggpht.com/...",
"connection_status": "active",
"has_comment_scope": true,
"has_messaging_scope": true,
"has_like_scope": false,
"needs_reconnect": false
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
| data[].id | string | platform_connections UUID. |
| data[].platform | 'instagram' | 'facebook' | 'youtube' | 'threads' | 'linkedin' | 'bluesky' | 'mastodon' | 'telegram' | 'google_business' | Which inbox-enabled platform the row is for. |
| data[].has_comment_scope | boolean | True when the connection can read + reply to post/video comment threads. |
| data[].has_messaging_scope | boolean | True when the connection can additionally sync + reply to DMs. IG/FB only — YouTube always mirrors has_comment_scope. |
| data[].has_like_scope | boolean | True when the connection can like/unlike comments on the account's behalf. YouTube, Threads, Bluesky, Mastodon, Telegram and Google Business always false (the YouTube Data API v3 has no comment-like endpoint). Instagram requires the Facebook Login for Business upgrade (instagram_manage_engagement). |
| data[].needs_reconnect | boolean | True when the row is unusable in the inbox — either no base scopes granted or the connection has been marked as needing reconnect. Sync + reply calls will fail until the user reconnects from the ShortSync dashboard. |
| data[].has_mentions_scope | boolean | True when the Threads connection has the threads_manage_mentions scope, which lets the inbox surface @mentions of the user's account alongside direct replies. Non-Threads connections always return true. |
List conversations
/inbox/conversations·inbox:readReturns inbox conversation threads (post/video comments and DMs) for the workspace with the same filter surface as the inbox UI. Offset-paginated via limit + offset; the response includes pagination.next_offset so you can walk to the next page without a separate count call.
Query parameters
| Field | Type | Default | Description |
|---|---|---|---|
| platform | 'instagram' | 'facebook' | 'youtube' | 'threads' | 'linkedin' | 'bluesky' | 'mastodon' | 'telegram' | 'google_business' | — | Filter to a single platform. Omit for all. |
| inbox_mode | 'all' | 'comments' | 'messages' | all | all returns both DMs and comment threads. comments narrows to post/video comment threads. messages narrows to DM threads (IG/FB only). |
| sort | 'recent' | 'most_liked' | 'most_unread' | 'oldest_unanswered' | recent | recent sorts by last activity. most_liked by like_count. most_unread by unread_count. oldest_unanswered by the oldest inbound message time — useful for a triage queue. |
| answered | 'all' | 'unanswered' | 'answered' | all | unanswered shows threads where the participant messaged more recently than your last reply (needs attention). answered is the inverse. |
| q | string | — | Case-insensitive substring search over participant username + last message preview. |
| unseen_only | '1' | — | When set, hide rows the workspace has already seen (last_seen_at >= last_message_at). |
| include_own | '1' | — | When set, also include the workspace's own top-level comment threads (hidden by default because they need no reply). |
| include_spam | '1' | — | When set, also include conversations the workspace has marked as spam (hidden by default). |
| media_video_id | string | — | Restrict to comment threads on a specific YouTube video id. |
| media_post_id | string | — | Restrict to comment threads on a specific IG/FB post/reel id. |
| limit | integer | 50 | 1–200 rows per page. |
| offset | integer | 0 | Row offset. Use the response's pagination.next_offset for the next page. |
Example request
curl "https://api.shortsync.app/v1/inbox/conversations?platform=instagram&answered=unanswered&limit=25" \
-H "Authorization: Bearer $TOKEN"Example response
{
"data": [
{
"id": "4d33b46d-8ebd-47c9-acfe-a6a49bf75087",
"workspace_id": "49aeb350-2023-462e-909d-322cbfe19930",
"platform": "instagram",
"thread_kind": "post_comments",
"participant_id": "1537982651155149",
"participant_username": "hilma_builds",
"participant_avatar_url": null,
"last_message_at": "2026-07-22T14:27:06+00:00",
"last_message_preview": "Testing here",
"last_inbound_at": "2026-07-22T14:27:06+00:00",
"last_outbound_at": null,
"last_seen_at": "2026-07-22T15:02:06+00:00",
"unread_count": 0,
"like_count": 2,
"liked_by_us": true,
"is_spam": false,
"answered_status": "unanswered",
"is_unseen": false,
"is_own_top_level_muted": false,
"platform_metadata": {
"post_id": "18450375271136963",
"post_permalink": "https://www.instagram.com/reel/DafLuI2gvN5/"
},
"external_conversation_id": "17920537482179894"
}
],
"pagination": {
"next_offset": 25,
"limit": 25,
"offset": 0
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data[].id | string | Conversation UUID. Pass to the messages, reply, like, and mark-* endpoints as the path parameter. |
| data[].thread_kind | 'dm' | 'post_comments' | 'video_comments' | dm = Instagram/Facebook Messenger DM thread. post_comments = one thread per top-level IG/FB post/reel comment (plus its replies). video_comments = same but for YouTube. |
| data[].answered_status | 'answered' | 'unanswered' | 'none' | null | unanswered when the participant messaged after your last reply. none when there's no inbound to answer (e.g. your own comment). |
| data[].last_seen_at | string | null | When any workspace member last scrolled this row into view (or marked it seen via the API). Compare against last_message_at for "new". |
| data[].platform_metadata | object | Platform-specific ids. Comment threads carry post_id (IG/FB) or video_id (YT) — pass these to POST /inbox/media/load-more to paginate older comments on the same media. |
| data[].external_conversation_id | string | The platform-side id (Meta thread id, YouTube comment id). Useful when correlating with data from the platform APIs directly. |
Get messages
/inbox/conversations/{id}/messages·inbox:readReturns the conversation row plus every persisted message, oldest-first. Cached — pass ?sync=1 to hit the platform API and upsert new messages before serving.
Query parameters
| Field | Type | Description |
|---|---|---|
| sync | '1' | When set, refreshes messages from the platform before returning. Adds one platform-API round trip and counts against upstream rate limits. |
Example request
curl "https://api.shortsync.app/v1/inbox/conversations/$CONV_ID/messages?sync=1" \
-H "Authorization: Bearer $TOKEN"Example response
{
"data": {
"conversation": {
"id": "4d33b46d-8ebd-47c9-acfe-a6a49bf75087",
"platform": "instagram",
"thread_kind": "post_comments",
"participant_username": "hilma_builds",
"unread_count": 0
},
"messages": [
{
"id": "c5d9538e-b39c-4fe2-a511-60466649b582",
"conversation_id": "4d33b46d-8ebd-47c9-acfe-a6a49bf75087",
"external_message_id": "17920537482179894",
"direction": "inbound",
"sender_id": "1537982651155149",
"sender_username": "hilma_builds",
"body": "Testing here",
"attachments": [],
"sent_at": "2026-07-22T14:27:06+00:00",
"reply_to_external_id": null,
"send_status": null,
"liked_by_us": false,
"like_count": 0,
"has_our_reply": true
}
]
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.messages[].direction | 'inbound' | 'outbound' | Inbound = the participant sent it. Outbound = you (or the connected account) sent it. |
| data.messages[].has_our_reply | boolean | Derived at read time. True on an inbound row when there's an outbound message that either explicitly references it (YouTubereply_to_external_id) or was sent after it in the same thread. Only meaningful for comment threads. |
| data.messages[].send_status | 'sent' | 'sending' | 'failed' | null | Delivery state for outbound messages. Null on inbound. |
| data.messages[].edited | boolean | True when the sender edited an Instagram DM after sending it. body holds the edited text. |
| data.messages[].story_link_url | string | null | On an Instagram DM that replies to a story: the link sticker on that story, when it has one. |
Sync inbox
/inbox/sync·inbox:writePulls fresh conversation threads and first-page messages from every DM-enabled connection in the workspace. Same operation as clicking the refresh button in the inbox UI. Optional platforms array narrows the sync to a subset. Each result counts messages_new (messages that weren't in the inbox before this sync), split into dms_new and comments_new.
Request body
| Field | Type | Description |
|---|---|---|
| platforms | ('instagram' | 'facebook' | 'youtube' | 'threads' | 'linkedin' | 'bluesky' | 'mastodon' | 'telegram' | 'google_business')[] | Omit to sync every inbox-enabled connection. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/sync \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UUID" \
-d '{"platforms":["instagram"]}'Example response
{
"data": {
"results": [
{
"platform": "instagram",
"platform_connection_id": "f39160db-8bfd-4c37-bff5-15f92da22139",
"conversations_upserted": 24,
"messages_upserted": 47,
"messages_new": 9,
"dms_new": 2,
"comments_new": 7,
"errors": []
}
]
}
}Reply
/inbox/conversations/{id}/reply·inbox:writePosts a reply to a comment thread (IG/FB post comments, YT video comments) or a DM (IG/FB). The reply is delivered via the platform API and the persisted outbound message row comes back in the response. An unknown conversation id returns 404 CONVERSATION_NOT_FOUND.
Request body
| Field | Type | Description |
|---|---|---|
| body | string | The reply text. Required and non-empty, unless you pass attachments. Instagram and Facebook Messenger DMs can be answered for 7 days after the participant's latest message (Meta's human agent window). Older DM threads return 400 REPLY_WINDOW_EXPIRED, and DM threads the participant has never written in (for example one started by a comment DM) return 400 REPLY_WINDOW_AWAITING_REPLY until they answer. Comment threads and the other platforms have no window. |
| attachments | { type: 'image' | 'file', url?: string, attachment_id?: string, title?: string }[] | Instagram DMs only. Up to 10 images (PNG, JPEG or GIF, 8 MB each), or one PDF on its own (25 MB). Each item needs exactly one of url, a public https URL, or attachment_id, a Meta attachment id (images only). Attachments go out first as their own message, then the text, with body limited to 1000 bytes. The response adds messages with every message sent. If the text fails after the attachments were delivered, the call still succeeds and returns warning, so resend only the text. |
| reply_to_message_id | string | Instagram and Facebook Messenger DMs only. The id (or external_message_id) of a message in this conversation to reply to. The reply shows that message as a quote, and the stored message gets its id in reply_to_external_id. If Meta refuses the quote, the reply is still sent without it and the response carries notice. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/conversations/$CONV_ID/reply \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UUID" \
-d '{"body":"Thanks for watching!"}'Example response
{
"data": {
"message": {
"id": "69252c7b-941c-4cf7-818e-f657bfc51d09",
"conversation_id": "4d33b46d-8ebd-47c9-acfe-a6a49bf75087",
"external_message_id": "18127819417589478",
"direction": "outbound",
"sender_username": "testaccount_shortsyncing",
"body": "Thanks for watching!",
"sent_at": "2026-08-03T07:10:22.67+00:00",
"send_status": "sent",
"liked_by_us": false,
"like_count": 0
}
}
}Like a conversation
/inbox/conversations/{id}/like·inbox:writeSets the "liked by us" state on a top-level comment thread. Instagram, Facebook and LinkedIn Company Pages only. Other platforms return 400 LIKE_UNSUPPORTED. Only comment threads can be liked; DM threads return the same code.
Request body
| Field | Type | Description |
|---|---|---|
| likedrequired | boolean | true to like, false to unlike. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/conversations/$CONV_ID/like \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"liked":true}'Example response
{ "data": { "liked_by_us": true } }Errors
| Field | Type | Description |
|---|---|---|
| 400 LIKE_UNSUPPORTED | A platform without comment likes (YouTube, Threads, Bluesky, Mastodon, Telegram, Google reviews), or a DM thread (only comment threads can be liked). | |
| 403 PLATFORM_SCOPE_MISSING | Instagram connection lacks instagram_manage_engagement. This needs the Facebook Login for Business upgrade, which a person has to finish in a browser, so retrying won't help until then. Response details carries platform, scope and upgrade_url: show that link to the user who connected the Instagram account, who opens it while signed in to ShortSync. Check has_like_scope on GET /inbox/connections before liking. |
Like a message
/inbox/messages/{id}/like·inbox:writeSame semantics as liking a conversation but scoped to a nested comment reply (a dm_messages row inside an IG/FB comment thread). DMs and YouTube reply rows can't be liked.
Request body
| Field | Type | Description |
|---|---|---|
| likedrequired | boolean | true to like, false to unlike. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/messages/$MSG_ID/like \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"liked":true}'Mark conversations seen
/inbox/conversations/mark-seen·inbox:writeBulk-set last_seen_at = now() for a batch of conversation ids. Local unless you set send_read_receipt. Rows outside the workspace are silently ignored.
Request body
| Field | Type | Description |
|---|---|---|
| conversation_idsrequired | string[] | Max 500 ids per call. |
| send_read_receipt | boolean | Also send Instagram's read receipt, so the participant sees their message was seen. Applies to at most 25 Instagram DMs per call whose last message is theirs and under 24 hours old. Best effort: it runs in the background and never fails the call. Default false. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/conversations/mark-seen \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"conversation_ids":["4d33b46d-...","ddd1ee08-..."]}'Example response
{
"data": {
"updated_ids": [
"4d33b46d-8ebd-47c9-acfe-a6a49bf75087",
"ddd1ee08-f4da-4a83-a491-438508adc0fe"
]
}
}Mark conversations spam
/inbox/conversations/mark-spam·inbox:writeBulk flip the local is_spam moderation flag. is_spam=true hides rows from GET /inbox/conversations unless include_spam=1 is set; is_spam=false restores them. Purely local — no platform hide/delete is performed, so unmarking always restores the row cleanly.
Request body
| Field | Type | Description |
|---|---|---|
| conversation_idsrequired | string[] | Max 500 ids per call. |
| is_spamrequired | boolean | true to mark, false to unmark. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/conversations/mark-spam \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"conversation_ids":["ddd1ee08-..."],"is_spam":true}'Load more comments
/inbox/media/load-more·inbox:writeFetches one more page of older comments for a specific YouTube video, Instagram post/reel, or Facebook post, and upserts them into the workspace's inbox. Cursor state is stored server-side, keyed on (workspace, platform, media), so consecutive calls walk further back through the comment history.
Request body
| Field | Type | Default | Description |
|---|---|---|---|
| platformrequired | 'instagram' | 'facebook' | 'youtube' | — | Which platform the media lives on. Only these three page through older comments; other inbox platforms return 400 BAD_REQUEST and get their comments through POST /inbox/sync. |
| media_source_idrequired | string | — | Platform-side media id. YouTube: video id. IG: media (post / reel) id. FB: post id. You'll find it on platform_metadata.video_id or .post_id from the conversations list. |
| force | boolean | false | When true, ignore the stored cursor and pull the newest page. Use when you want to catch comments that arrived after the last pagination — the platforms paginate newest→oldest, so normal load-more never catches new comments. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/media/load-more \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"platform":"instagram","media_source_id":"18450375271136963"}'Example response
{
"data": {
"new_count": 6,
"total_conversations_returned": 6,
"exhausted": true
}
}Response fields
| Field | Type | Description |
|---|---|---|
| data.new_count | integer | How many of the returned conversations were genuinely new (didn't already exist in the cache). |
| data.total_conversations_returned | integer | Total rows the platform returned on this page (new + already-known). |
| data.exhausted | boolean | True when the platform has no more older pages. Once true, subsequent calls no-op until the workspace posts new comments or you send force=true. |
List saved replies
/inbox/saved-replies·inbox:readReturns the workspace's saved replies, sorted by name. Saved replies are reusable text shared by everyone in the workspace. They are never sent on their own: to answer a thread, send the text you want with POST /inbox/conversations/{id}/reply.
Example request
curl https://api.shortsync.app/v1/inbox/saved-replies \
-H "Authorization: Bearer $TOKEN"Example response
{
"data": [
{
"id": "7b1f0a52-3c1e-4c58-9a64-2f6f1d0e8b11",
"workspace_id": "49aeb350-2023-462e-909d-322cbfe19930",
"created_by": "c0a8d2e4-51f7-4e0b-8d3a-6b7e9f102a34",
"name": "Thanks",
"content": "Thanks for watching!",
"created_at": "2026-11-05T09:12:44+00:00",
"updated_at": "2026-11-05T09:12:44+00:00"
}
]
}Response fields
| Field | Type | Description |
|---|---|---|
| data[].created_by | string | null | User who created it. Null when that account has been deleted. |
Create a saved reply
/inbox/saved-replies·inbox:writeAdds a saved reply to the workspace. Nothing is sent to any platform. The API key's creator must not be a client in the workspace.
Request body
| Field | Type | Description |
|---|---|---|
| namerequired | string | Up to 50 characters. Unique within the workspace. |
| contentrequired | string | The reply text. Up to 5,000 characters. |
Example request
curl -X POST https://api.shortsync.app/v1/inbox/saved-replies \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $UUID" \
-d '{"name":"Thanks","content":"Thanks for watching!"}'Example response
{
"data": {
"id": "7b1f0a52-3c1e-4c58-9a64-2f6f1d0e8b11",
"workspace_id": "49aeb350-2023-462e-909d-322cbfe19930",
"created_by": "c0a8d2e4-51f7-4e0b-8d3a-6b7e9f102a34",
"name": "Thanks",
"content": "Thanks for watching!",
"created_at": "2026-11-05T09:12:44+00:00",
"updated_at": "2026-11-05T09:12:44+00:00"
}
}Errors
| Field | Type | Description |
|---|---|---|
| 400 DUPLICATE_NAME | The workspace already has a saved reply with this name. | |
| 403 CLIENT_ACTION_FORBIDDEN | Clients can read saved replies but not create, update or delete them. |
Update a saved reply
/inbox/saved-replies/{id}·inbox:writeChanges the fields you pass and returns the updated saved reply in the same shape as create. Returns 404 SAVED_REPLY_NOT_FOUND when the id isn't in this workspace.
Request body
| Field | Type | Description |
|---|---|---|
| name | string | Up to 50 characters. Unique within the workspace. |
| content | string | The reply text. Up to 5,000 characters. |
Example request
curl -X PATCH https://api.shortsync.app/v1/inbox/saved-replies/$SAVED_REPLY_ID \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"content":"Thanks so much for watching!"}'Delete a saved reply
/inbox/saved-replies/{id}·inbox:writeRemoves the saved reply for the whole workspace. Replies already sent aren't affected. Responds with 204 No Content, or 404 SAVED_REPLY_NOT_FOUND when the id isn't in this workspace.
Example request
curl -X DELETE https://api.shortsync.app/v1/inbox/saved-replies/$SAVED_REPLY_ID \
-H "Authorization: Bearer $TOKEN"