---
title: "List conversations"
method: GET
path: "/v1/messaging/inbox/conversations"
tags: ["Messages"]
---

# List conversations

`GET /v1/messaging/inbox/conversations`

## Request

- Base URL: `https://apihub.co.il`
- URL: `https://apihub.co.il/v1/messaging/inbox/conversations`
- Auth: HTTP bearer

Fetch conversations (DMs) from all connected messaging accounts in a single API call. Supports filtering by profile and platform. Results are aggregated and deduplicated.

Supported platforms: Facebook, Instagram, X, Bluesky, Reddit, Telegram.

**X limitation.** X has replaced traditional DMs with encrypted "X Chat" for many accounts. Messages sent or received through encrypted X Chat are not accessible via X's API (the /2/dm_events endpoint only returns legacy unencrypted DMs). This means some X conversations may show only outgoing messages or appear empty. This is an X platform limitation that affects all third-party applications. See X's docs on encrypted messaging for more details.

**Instagram and Facebook pre-connect history.** When one of these accounts is connected, Zernio replays the DM history the account already holds on Meta, so conversations that began before the account was connected appear here. Up to 500 conversations per account are replayed.

- The replay runs in the background and can finish after a listing you have already taken, and replayed conversations keep their original lastMessageAt, so they sort into date order rather than appearing at the top. If you mirror this endpoint into your own store, re-run the sweep rather than relying on a single pass at connect time.
- Replayed history emits no webhooks and is stored as already read, so it never affects unread counts.
- Threads that Meta refuses to serve are skipped, and an account whose Instagram "connected tools" message access is turned off is not replayed at all.


**Billing:** Read (free unless it says otherwise) · **Rate limit:** 120/min

## Query parameters

- `limit` integer: Maximum number of conversations to return; values above 100 are served as 100.
- `cursor` string: Pagination cursor for next page
- `folder` 'inbox' | 'requests': requests lists Facebook and Instagram Message Requests (threads from people the account has not accepted) live from Meta, each item with `folder: requests`. Meta has no accept call: replying moves a thread to the inbox, which is what POST /v1/inbox/conversations/{conversationId}/accept does. When Meta will not list the folder for the one account asked (`accountId`), the call answers 400 PLATFORM_LIMITATION; across several accounts the refusal is reported per account in meta.failedAccounts. Instagram accounts connected with Instagram Login answer PLATFORM_LIMITATION (Meta does not expose the folder on that login); Facebook and Instagram via Facebook Login are served. One page of up to `limit` threads; `pagination.hasMore` is true when threads past `limit` were cut (narrow with `accountId`), `pagination.nextCursor` is always null and a `cursor` answers 400.
- `status` 'active' | 'archived': Filter by conversation status
- `platform` 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram' | 'whatsapp' | 'imessage': Filter by platform
- `accountId` string: Filter by specific account ID
- `sortOrder` 'asc' | 'desc': Sort order by updated time

## Headers

- `Idempotency-Key` string
- `X-Tag` string

## Response `200`

Completed

- object
  - `id` string: Execution id — stable across internal retries; use it with GET /v1/executions/{id}
  - `status` 'pending' | 'processing' | 'completed' | 'partial' | 'failed' | 'cancelled' | 'timeout'
  - `operation` string
  - `tag` string, nullable: Your X-Tag, if sent
  - `created_at` string, date-time
  - `completed_at` string, date-time, nullable
  - `output` object: Operation result (see each operation). While a Studio render is processing: `stage` (queued · transcribing · downloading · preparing · cleaning_voice · mixing_audio · rendering · finishing), `phase` (the engine's: download · prepare · voice · audio · encode · qa · upload, or null), `progress` (a percent, 0–100) and `progress_fraction` (0–1), `eta_seconds` (seconds left, never below 0) and `estimate_seconds`
    - `data` object[]
      - `id` string: Opaque conversation identifier. Pass it back verbatim to any /v1/inbox/conversations/{conversationId} route; do not assume a fixed format.
      - `url` string, nullable: Direct link to open the conversation on the platform (if available)
      - `folder` 'requests': Present only on items listed with folder=requests: a Message Request the account has not accepted yet.
      - `status` 'active' | 'archived'
      - `isGroup` boolean: iMessage only, true for a group thread. Manage it through the /v1/imessage/groups/{conversationId} endpoints.
      - `metadata` object, nullable: Click attribution for a conversation that started from a Meta ad or a ref-tagged ig.me / m.me link. Absent when the conversation did not originate from an attributable click. Captured from the referral Meta delivers for the click. If the same person later arrives through a different ad or link, the original values are kept, so the first referral wins; read the fresh referral per click on the `message.received` / `referral.received` webhooks instead. One exception on WhatsApp: when Meta omits `ctwa_clid` from that referral, a later Meta automatic event can supply it and refresh `ctwa_captured_at`, so treat `ctwa_captured_at` as the time Zernio stored the value, not the time of the click. Two families of keys, one per surface. They never appear together: - `ctwa_*` is WhatsApp Click-to-WhatsApp. The ad ID is `ctwa_source_id`. There is no `meta_ad_id` on WhatsApp. - `meta_ad_*` is Instagram Click-to-Direct, Facebook Messenger Click-to-Message, and ig.me / m.me ref links. The ad ID is `meta_ad_id` (ad clicks only; a link capture carries `meta_ad_ref` without it). `ctwa_clid` never appears on these platforms. Every key is optional and only the keys Meta supplied are returned, so read defensively. Meta does not send a campaign or ad set ID, so none is exposed here. More keys may be added over time. Treat any key you do not recognise as an opaque string. Key names differ from the `message.received` webhook on purpose. The webhook forwards Meta's referral verbatim (`ad_id`, `source`, `type`) while the stored conversation record uses the prefixed names below. Renaming either side would break existing integrations, so both spellings are kept.
        - `ctwa_clid` string: WhatsApp only. Meta's click identifier, the value to forward to the Meta Conversions API for Business Messaging. Meta omits it on some numbers, so a WhatsApp referral can arrive without it.
        - `meta_ad_id` string: Instagram and Facebook only. The Meta ad ID the user clicked. Present for ad clicks; absent when the capture came from an ig.me / m.me ref link.
        - `meta_ad_ref` string: Instagram and Facebook only. The ref parameter passed through from the ad creative or the ig.me / m.me link.
        - `meta_ad_type` string: Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
        - `ctwa_headline` string: WhatsApp only. Headline of the ad creative at click time.
        - `meta_ad_title` string: Instagram and Facebook only. Title of the ad creative at click time.
        - `ctwa_source_id` string: WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
        - `meta_ad_source` string: Instagram and Facebook only. Meta-supplied source identifier: ADS for ad clicks; SHORTLINK, SHORTLINKS or IGME-SOURCE-LINK for ref links (treat as opaque).
        - `ctwa_source_url` string: WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
        - `meta_ad_flow_id` string: Instagram and Facebook only. The Meta flow the ad launched, for flow ads.
        - `meta_ad_post_id` string: Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
        - `ctwa_captured_at` string, date-time: WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
        - `ctwa_source_type` string: WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
        - `meta_ad_photo_url` string: Instagram and Facebook only. Image of the ad creative at click time.
        - `meta_ad_video_url` string: Instagram and Facebook only. Video of the ad creative at click time.
        - `meta_ad_product_id` string: Instagram and Facebook only. The catalogue product the user clicked, for product ads.
        - `meta_ad_captured_at` string, date-time: Instagram and Facebook only. When Zernio stored this referral. Always present when an Instagram or Facebook referral was captured.
      - `platform` string
      - `accountId` string
      - `lastMessage` string
      - `unreadCount` integer, nullable: Number of unread messages
      - `updatedTime` string, date-time
      - `participantId` string
      - `threadControl` 'app' | 'ai_agent' | 'other': Present once a handover has touched the thread (WhatsApp, Facebook, Instagram). ai_agent: Meta Business Agent answers (WhatsApp) and new inbound arrive flagged metadata.standby; app: you hold control; other: another app does (a WhatsApp partner, or a Messenger / Instagram receiver such as Page Inbox). Change it with POST /v1/inbox/conversations/{conversationId}/thread-control.
      - `accountUsername` string
      - `participantName` string
      - `instagramProfile` object, nullable: Instagram profile data for the participant. Only present for Instagram conversations.
        - `fetchedAt` string, date-time, nullable: When this profile data was last fetched from Instagram
        - `isFollower` boolean, nullable: Whether the participant follows your Instagram business account
        - `isVerified` boolean, nullable: Whether the participant is a verified Instagram user
        - `isFollowing` boolean, nullable: Whether your Instagram business account follows the participant
        - `followerCount` integer, nullable: The participant's follower count on Instagram
      - `whatsappUsername` string: WhatsApp only. The participant's WhatsApp username (e.g. `jane.shop`, no leading @). Not a stable identifier, because users can change it: useful for display, not recommended as an identity anchor. Captured from inbound messages, so older threads fill in on their next inbound.
      - `participantPicture` string, nullable
      - `businessScopedUserId` string: WhatsApp only. Meta business-scoped user ID (BSUID), the stable identity anchor; present when Meta has sent it for this participant.
      - `participantVerifiedType` 'blue' | 'government' | 'business' | 'none', nullable: X verified badge type. Only present for X conversations.
    - `meta` object
      - `lastUpdated` string, date-time
      - `accountsFailed` integer
      - `failedAccounts` object[]
        - `code` string, nullable: Error code if available
        - `error` string
        - `platform` string
        - `accountId` string
        - `retryAfter` integer, nullable: Seconds to wait before retry (rate limits)
        - `accountUsername` string, nullable
      - `accountsQueried` integer
      - `accountsSkipped` object[]: Connected accounts that were not queried: their platform does not support this feature, or the account is not enabled for it
        - `platform` string
        - `accountId` string
    - `pagination` object
      - `hasMore` boolean
      - `nextCursor` string, nullable
  - `error` string, nullable
  - `usage` object
    - `credits_charged` number, nullable
    - `credits_reserved` number
    - `estimated_credits` number
    - `cost_source` 'provider_reported' | 'calculated' | 'estimated' | 'null', nullable
    - `provider_usage` object, nullable: Normalised consumption, e.g. { VIDEO_SECOND: 22.4 }
  - `balance` object
    - `available` number
    - `reserved` number

## Other responses

- `400`: Invalid input
- `402`: Insufficient credits / project budget
- `404`: Resource not found (or not yours)
- `429`: Rate limited
- `503`: Service temporarily paused

---

[API](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai.md) · [All operations](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/llms.txt) · [OpenAPI document](https://skmtc.dev/apihub/apis/apihub-one-api-for-chat-image-video-ai/revisions/a8caa42835ce?raw)