OMomnisocials
Inbox

Get next conversation

Changed on

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).

get/inbox/next

Request

  • Base URL
    https://api.omnisocials.com/v1
  • URL
    https://api.omnisocials.com/v1/inbox/next
  • Auth
    HTTP bearer

Query parameters

platform'instagram' | 'facebook' | 'linkedin' | 'tiktok' | 'youtube' | 'x' | 'threads'

Only items from one platform.

type'dm' | 'comment' | 'mention'

Only items of one type.

order'oldest' | 'newest'

oldest serves the item that has waited longest first; newest the most recent.

include_readboolean

Also serve items that were marked read but never answered.

excludestring
Example:instagram_comment_17912345678901234,instagram_comment_17912345678905678

Comma-separated conversation ids to leave out of this call (a session-local skip; up to 100).

Response

The next item, or null when nothing is waiting

remaininginteger

Unanswered items still waiting after this one (capped at 500). 0 when data is null.

Example response

{
  "data": {
    "conversation": {
      "conversation_id": "instagram_comment_17912345678901234",
      "type": "comment",
      "participant": {
        "name": "Jamie Rivera",
        "username": "jamierivera",
        "profile_picture": "https://example.com/avatar.jpg"
      },
      "unread_count": 1,
      "last_message": {
        "id": "88231",
        "text": "What size is this?",
        "timestamp": "2026-10-21T09:00:00.000Z"
      },
      "post": {
        "id": "17912345678901234",
        "caption": "Our autumn menu is here. #autumnmenu",
        "thumbnail": "https://example.com/photo.jpg",
        "url": "https://www.instagram.com/p/Cxyz123ABC/",
        "media_type": "IMAGE"
      }
    },
    "message": {
      "id": "88231",
      "conversation_id": "instagram_comment_17912345678901234",
      "platform": "instagram",
      "type": "comment",
      "text": "What size is this?",
      "timestamp": "2026-10-21T09:00:00.000Z",
      "attachment": {
        "url": "https://example.com/photo.jpg"
      },
      "sender": {
        "name": "Jamie Rivera",
        "username": "jamierivera",
        "profile_picture": "https://example.com/avatar.jpg"
      },
      "post": {
        "id": "17912345678901234",
        "caption": "Our autumn menu is here. #autumnmenu",
        "thumbnail": "https://example.com/photo.jpg",
        "url": "https://www.instagram.com/p/Cxyz123ABC/",
        "media_type": "IMAGE"
      }
    },
    "messages": [
      {
        "id": "88231",
        "conversation_id": "instagram_comment_17912345678901234",
        "platform": "instagram",
        "type": "comment",
        "text": "What size is this?",
        "timestamp": "2026-10-21T09:00:00.000Z",
        "attachment": {
          "url": "https://example.com/photo.jpg"
        },
        "sender": {
          "name": "Jamie Rivera",
          "username": "jamierivera",
          "profile_picture": "https://example.com/avatar.jpg"
        },
        "post": {
          "id": "17912345678901234",
          "caption": "Our autumn menu is here. #autumnmenu",
          "thumbnail": "https://example.com/photo.jpg",
          "url": "https://www.instagram.com/p/Cxyz123ABC/",
          "media_type": "IMAGE"
        }
      }
    ],
    "reply_window": {
      "open": true,
      "closes_at": "2026-10-22T09:00:00.000Z"
    }
  },
  "remaining": 4
}

Changes

  • 79cdeec29f82Revision changes
    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property /// to the response with the status

  • 5a093275ff4aRevision changes
    • info

      added the optional property / to the response with the status