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

EndpointMethodPathScopePurpose
List connectionsGET/inbox/connectionsinbox:readWhich platform accounts are wired into the inbox
List conversationsGET/inbox/conversationsinbox:readFiltered + paginated thread list
Get messagesGET/inbox/conversations/{id}/messagesinbox:readOne conversation's full message history
Sync inboxPOST/inbox/syncinbox:writePull fresh threads + messages from every connection
ReplyPOST/inbox/conversations/{id}/replyinbox:writePost a reply to a comment thread or DM
Like a conversationPOST/inbox/conversations/{id}/likeinbox:writeLike/unlike a top-level comment thread (Instagram, Facebook, LinkedIn)
Like a messagePOST/inbox/messages/{id}/likeinbox:writeLike/unlike a nested comment reply (Instagram, Facebook, LinkedIn)
Mark conversations seenPOST/inbox/conversations/mark-seeninbox:writeBatch mark rows as read for the workspace
Mark conversations spamPOST/inbox/conversations/mark-spaminbox:writeBulk flip the local spam moderation flag
Load more commentsPOST/inbox/media/load-moreinbox:writePaginate deeper into a specific video/post's comment history
List saved repliesGET/inbox/saved-repliesinbox:readThe workspace's reusable reply text
Create a saved replyPOST/inbox/saved-repliesinbox:writeAdd a saved reply for the whole workspace
Update a saved replyPATCH/inbox/saved-replies/{id}inbox:writeChange a saved reply's name or content
Delete a saved replyDELETE/inbox/saved-replies/{id}inbox:writeRemove a saved reply

List connections

GET/inbox/connections·inbox:read

Returns 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

bash
curl https://api.shortsync.app/v1/inbox/connections \
  -H "Authorization: Bearer $TOKEN"

Example response

json
{
  "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

FieldTypeDescription
data[].idstringplatform_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_scopebooleanTrue when the connection can read + reply to post/video comment threads.
data[].has_messaging_scopebooleanTrue when the connection can additionally sync + reply to DMs. IG/FB only — YouTube always mirrors has_comment_scope.
data[].has_like_scopebooleanTrue 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_reconnectbooleanTrue 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_scopebooleanTrue 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

GET/inbox/conversations·inbox:read

Returns 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

FieldTypeDefaultDescription
platform'instagram' | 'facebook' | 'youtube' | 'threads' | 'linkedin' | 'bluesky' | 'mastodon' | 'telegram' | 'google_business'—Filter to a single platform. Omit for all.
inbox_mode'all' | 'comments' | 'messages'allall 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'recentrecent 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'allunanswered shows threads where the participant messaged more recently than your last reply (needs attention). answered is the inverse.
qstring—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_idstring—Restrict to comment threads on a specific YouTube video id.
media_post_idstring—Restrict to comment threads on a specific IG/FB post/reel id.
limitinteger501–200 rows per page.
offsetinteger0Row offset. Use the response's pagination.next_offset for the next page.

Example request

bash
curl "https://api.shortsync.app/v1/inbox/conversations?platform=instagram&answered=unanswered&limit=25" \
  -H "Authorization: Bearer $TOKEN"

Example response

json
{
  "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

FieldTypeDescription
data[].idstringConversation 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' | nullunanswered when the participant messaged after your last reply. none when there's no inbound to answer (e.g. your own comment).
data[].last_seen_atstring | nullWhen 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_metadataobjectPlatform-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_idstringThe platform-side id (Meta thread id, YouTube comment id). Useful when correlating with data from the platform APIs directly.

Get messages

GET/inbox/conversations/{id}/messages·inbox:read

Returns 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

FieldTypeDescription
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

bash
curl "https://api.shortsync.app/v1/inbox/conversations/$CONV_ID/messages?sync=1" \
  -H "Authorization: Bearer $TOKEN"

Example response

json
{
  "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

FieldTypeDescription
data.messages[].direction'inbound' | 'outbound'Inbound = the participant sent it. Outbound = you (or the connected account) sent it.
data.messages[].has_our_replybooleanDerived 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' | nullDelivery state for outbound messages. Null on inbound.
data.messages[].editedbooleanTrue when the sender edited an Instagram DM after sending it. body holds the edited text.
data.messages[].story_link_urlstring | nullOn an Instagram DM that replies to a story: the link sticker on that story, when it has one.

Sync inbox

POST/inbox/sync·inbox:write

Pulls 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

FieldTypeDescription
platforms('instagram' | 'facebook' | 'youtube' | 'threads' | 'linkedin' | 'bluesky' | 'mastodon' | 'telegram' | 'google_business')[]Omit to sync every inbox-enabled connection.

Example request

bash
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

json
{
  "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

POST/inbox/conversations/{id}/reply·inbox:write

Posts 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

FieldTypeDescription
bodystringThe 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_idstringInstagram 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

bash
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

json
{
  "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

POST/inbox/conversations/{id}/like·inbox:write

Sets 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

FieldTypeDescription
likedrequiredbooleantrue to like, false to unlike.

Example request

bash
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

json
{ "data": { "liked_by_us": true } }

Errors

FieldTypeDescription
400 LIKE_UNSUPPORTEDA platform without comment likes (YouTube, Threads, Bluesky, Mastodon, Telegram, Google reviews), or a DM thread (only comment threads can be liked).
403 PLATFORM_SCOPE_MISSINGInstagram 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

POST/inbox/messages/{id}/like·inbox:write

Same 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

FieldTypeDescription
likedrequiredbooleantrue to like, false to unlike.

Example request

bash
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

POST/inbox/conversations/mark-seen·inbox:write

Bulk-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

FieldTypeDescription
conversation_idsrequiredstring[]Max 500 ids per call.
send_read_receiptbooleanAlso 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

bash
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

json
{
  "data": {
    "updated_ids": [
      "4d33b46d-8ebd-47c9-acfe-a6a49bf75087",
      "ddd1ee08-f4da-4a83-a491-438508adc0fe"
    ]
  }
}

Mark conversations spam

POST/inbox/conversations/mark-spam·inbox:write

Bulk 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

FieldTypeDescription
conversation_idsrequiredstring[]Max 500 ids per call.
is_spamrequiredbooleantrue to mark, false to unmark.

Example request

bash
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

POST/inbox/media/load-more·inbox:write

Fetches 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

FieldTypeDefaultDescription
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_idrequiredstring—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.
forcebooleanfalseWhen 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

bash
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

json
{
  "data": {
    "new_count": 6,
    "total_conversations_returned": 6,
    "exhausted": true
  }
}

Response fields

FieldTypeDescription
data.new_countintegerHow many of the returned conversations were genuinely new (didn't already exist in the cache).
data.total_conversations_returnedintegerTotal rows the platform returned on this page (new + already-known).
data.exhaustedbooleanTrue 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

GET/inbox/saved-replies·inbox:read

Returns 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

bash
curl https://api.shortsync.app/v1/inbox/saved-replies \
  -H "Authorization: Bearer $TOKEN"

Example response

json
{
  "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

FieldTypeDescription
data[].created_bystring | nullUser who created it. Null when that account has been deleted.

Create a saved reply

POST/inbox/saved-replies·inbox:write

Adds 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

FieldTypeDescription
namerequiredstringUp to 50 characters. Unique within the workspace.
contentrequiredstringThe reply text. Up to 5,000 characters.

Example request

bash
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

json
{
  "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

FieldTypeDescription
400 DUPLICATE_NAMEThe workspace already has a saved reply with this name.
403 CLIENT_ACTION_FORBIDDENClients can read saved replies but not create, update or delete them.

Update a saved reply

PATCH/inbox/saved-replies/{id}·inbox:write

Changes 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

FieldTypeDescription
namestringUp to 50 characters. Unique within the workspace.
contentstringThe reply text. Up to 5,000 characters.

Example request

bash
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

DELETE/inbox/saved-replies/{id}·inbox:write

Removes 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

bash
curl -X DELETE https://api.shortsync.app/v1/inbox/saved-replies/$SAVED_REPLY_ID \
  -H "Authorization: Bearer $TOKEN"