--- title: "Get next conversation" method: GET path: "/inbox/next" tags: ["Inbox"] --- # Get next conversation `GET /inbox/next` ## Request - Base URL: `https://api.omnisocials.com/v1` - URL: `https://api.omnisocials.com/v1/inbox/next` - Auth: HTTP bearer A work queue for answering the inbox. Returns one item that still needs a reply, together with its conversation so far and the post it belongs to, so a reply can be drafted from one call. An item needs an answer when it is the customer's latest DM with no reply after it, or a comment/mention that has not been replied to and is not hidden. Order: DMs that can still be answered come first (Instagram/Facebook DMs inside Meta's 24-hour window, the one whose window closes soonest first, and X DMs), then Instagram/Facebook DMs whose window has closed (served with `reply_window.open = false`: answer them from the native app or mark them read), then comments and mentions, oldest first by default. Pass `message.id` as `message_id` to the reply endpoint so a comment reply lands under the served comment. Replies typed in the native apps count as answers (they are mirrored into the inbox), so a thread a colleague answered on their phone is not served again. Instagram mentions are skipped (no reply path). Only unread items are served by default: marking a conversation read (POST /inbox/conversations/{id}/read) is how to skip one for good; pass `include_read=true` to include read-but-unanswered items. Looks at the last 30 days of activity. To chain the queue, pass `include_next: true` to the reply endpoint and it returns the next item in the same response. Requires the `inbox:read` scope (API keys) or the `access_social_inbox` permission (OAuth/MCP). ## Query parameters - `platform` 'instagram' | 'facebook' | 'linkedin' | 'tiktok' | 'youtube' | 'x' | 'threads' - `type` 'dm' | 'comment' | 'mention' - `order` 'oldest' | 'newest' - `include_read` boolean - `exclude` string ## Response `200` The next item, or null when nothing is waiting - object - `data` InboxNextUnanswered, nullable: The next conversation that needs an answer, with everything needed to draft the reply. Null when the queue is empty. - `conversation` InboxConversation - `conversation_id` string - `platform` 'instagram' | 'facebook' | 'linkedin' | 'tiktok' | 'youtube' | 'x' | 'threads' - `type` 'dm' | 'comment' | 'mention': dm = direct message; comment/mention = public interaction. LinkedIn is comment/mention only; TikTok and YouTube are comment only; X is dm only; Threads is comment (replies on your posts) and mention only. - `participant` InboxParticipant - `id` string: Platform-scoped id of the other party - `name` string - `username` string - `profile_picture` string, nullable - `unread_count` integer: Unread incoming messages in this conversation - `last_message` object - `id` string - `direction` 'incoming' | 'outgoing' - `text` string - `timestamp` string, date-time - `is_read` boolean - `post` InboxPostContext, nullable: The post a comment/mention conversation belongs to, so a reply can be drafted with the post in view ("what size is this?" needs the caption and the picture). Null for DMs. `url` is the public link to the post when the platform provides one (Instagram, Facebook, YouTube, TikTok, LinkedIn, Threads); `media_type` is the platform's label (e.g. IMAGE, VIDEO, CAROUSEL_ALBUM on Instagram) when known. - `id` string, nullable - `caption` string, nullable - `thumbnail` string, nullable: Image URL of the post (or the video's cover) - `url` string, nullable - `media_type` string, nullable - `message` InboxMessage - `id` string - `conversation_id` string - `platform` string - `type` 'dm' | 'comment' | 'mention' - `direction` 'incoming' | 'outgoing' - `text` string - `timestamp` string, date-time - `is_read` boolean - `is_replied` boolean - `reaction` string, nullable - `parent_comment_id` string, nullable - `hidden` boolean, nullable: Comments only: true when the comment is hidden on the platform (see POST /inbox/messages/{id}/hide). Null for DMs. - `liked` boolean, nullable: Incoming Facebook, LinkedIn Page and TikTok comments: true when the connected account liked the comment (see POST /inbox/messages/{id}/like). Facebook and LinkedIn report likes made through OmniSocials; TikTok also reports likes made in the TikTok app. Null for DMs, outgoing messages and the other platforms. - `permalink` string, nullable: Link to the reply or mentioning post on the platform, when known - `attachment` object, nullable: Media sent with this message, when present. Incoming Instagram/Facebook DM images, videos, voice messages, and story mentions are re-hosted on our CDN so the URL stays valid indefinitely (the platform's own URL is short-lived). `type` reflects the fetched bytes, not the platform's label: a photo the platform sent under an unlabelled attachment type is `image`, a story mention that is really an MP4 is `video`. `type: file` covers media we could fetch but could not classify. `type: link` means the platform's URL did not point at media (for example a shared post that resolves to an instagram.com page); `url` is then the platform's own link, not re-hosted, and may require login or expire. - `url` string - `type` 'image' | 'video' | 'audio' | 'file' | 'link' - `sender` InboxParticipant - `id` string: Platform-scoped id of the other party - `name` string - `username` string - `profile_picture` string, nullable - `post` InboxPostContext, nullable: The post a comment/mention conversation belongs to, so a reply can be drafted with the post in view ("what size is this?" needs the caption and the picture). Null for DMs. `url` is the public link to the post when the platform provides one (Instagram, Facebook, YouTube, TikTok, LinkedIn, Threads); `media_type` is the platform's label (e.g. IMAGE, VIDEO, CAROUSEL_ALBUM on Instagram) when known. - `id` string, nullable - `caption` string, nullable - `thumbnail` string, nullable: Image URL of the post (or the video's cover) - `url` string, nullable - `media_type` string, nullable - `messages` InboxMessage[]: The conversation so far, oldest first (the most recent 50 messages for long DM threads). - `id` string - `conversation_id` string - `platform` string - `type` 'dm' | 'comment' | 'mention' - `direction` 'incoming' | 'outgoing' - `text` string - `timestamp` string, date-time - `is_read` boolean - `is_replied` boolean - `reaction` string, nullable - `parent_comment_id` string, nullable - `hidden` boolean, nullable: Comments only: true when the comment is hidden on the platform (see POST /inbox/messages/{id}/hide). Null for DMs. - `liked` boolean, nullable: Incoming Facebook, LinkedIn Page and TikTok comments: true when the connected account liked the comment (see POST /inbox/messages/{id}/like). Facebook and LinkedIn report likes made through OmniSocials; TikTok also reports likes made in the TikTok app. Null for DMs, outgoing messages and the other platforms. - `permalink` string, nullable: Link to the reply or mentioning post on the platform, when known - `attachment` object, nullable: Media sent with this message, when present. Incoming Instagram/Facebook DM images, videos, voice messages, and story mentions are re-hosted on our CDN so the URL stays valid indefinitely (the platform's own URL is short-lived). `type` reflects the fetched bytes, not the platform's label: a photo the platform sent under an unlabelled attachment type is `image`, a story mention that is really an MP4 is `video`. `type: file` covers media we could fetch but could not classify. `type: link` means the platform's URL did not point at media (for example a shared post that resolves to an instagram.com page); `url` is then the platform's own link, not re-hosted, and may require login or expire. - `url` string - `type` 'image' | 'video' | 'audio' | 'file' | 'link' - `sender` InboxParticipant - `id` string: Platform-scoped id of the other party - `name` string - `username` string - `profile_picture` string, nullable - `post` InboxPostContext, nullable: The post a comment/mention conversation belongs to, so a reply can be drafted with the post in view ("what size is this?" needs the caption and the picture). Null for DMs. `url` is the public link to the post when the platform provides one (Instagram, Facebook, YouTube, TikTok, LinkedIn, Threads); `media_type` is the platform's label (e.g. IMAGE, VIDEO, CAROUSEL_ALBUM on Instagram) when known. - `id` string, nullable - `caption` string, nullable - `thumbnail` string, nullable: Image URL of the post (or the video's cover) - `url` string, nullable - `media_type` string, nullable - `reply_window` object: Whether a reply can still be sent through the API. Only Instagram and Facebook DMs have a window (Meta: 24 hours after the customer's last message); every other item has `open: true` and `closes_at: null`. When `open` is false the item is still served (the customer is still waiting) but the reply endpoint answers 422 `outside_messaging_window`: answer it from the native app (that reply is mirrored into the inbox and clears the item) or mark the conversation read to skip it. - `open` boolean - `closes_at` string, date-time, nullable: When the window closes or closed (customer's last message + 24 h); null when there is no window. - `remaining` integer: Unanswered items still waiting after this one (capped at 500). 0 when `data` is null. ## Other responses - `400`: `validation_error`: unknown platform, type or order ## Changes - **2026-10-27** `79cdeec29f82`: 2 info - added the optional property `data/message/allOf[#/components/schemas/InboxMessage]/liked` to the response with the `200` status - added the optional property `data/messages/items/liked` to the response with the `200` status - **2026-09-25** `5a093275ff4a`: 1 info - added the optional property `data/reply_window` to the response with the `200` status - **2026-09-07** `bff746fd6191`: 1 info - endpoint added [Operation history](https://skmtc.dev/omnisocials/apis/omnisocials-api/changes/inbox/next/get.md) --- [API](https://skmtc.dev/omnisocials/apis/omnisocials-api.md) - [All operations](https://skmtc.dev/omnisocials/apis/omnisocials-api/llms.txt) - [OpenAPI document](https://skmtc.dev/omnisocials/apis/omnisocials-api/revisions/46e479c09474?raw)