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

# List conversations

`GET /v1/inbox/conversations`

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, Twitter/X, Bluesky, Reddit, Telegram.

Twitter/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 Twitter/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.

## Query parameters

- `profileId` string
- `platform` 'facebook' | 'instagram' | 'twitter' | 'bluesky' | 'reddit' | 'telegram' | 'whatsapp'
- `status` 'active' | 'archived'
- `sortOrder` 'asc' | 'desc'
- `limit` integer
- `cursor` string
- `accountId` string

## Response `200`

Aggregated conversations

- object
  - `data` object[]
    - `id` string — Opaque conversation identifier. Pass it back verbatim to any /v1/inbox/conversations/{conversationId} route; do not assume a fixed format.
    - `platform` string
    - `accountId` string
    - `accountUsername` string
    - `participantId` string
    - `participantName` string
    - `participantPicture` string, nullable
    - `participantVerifiedType` 'blue' | 'government' | 'business' | 'none', nullable — X/Twitter verified badge type. Only present for Twitter/X conversations.
    - `lastMessage` string
    - `updatedTime` string, date-time
    - `status` 'active' | 'archived'
    - `unreadCount` integer, nullable — Number of unread messages
    - `url` string, nullable — Direct link to open the conversation on the platform (if available)
    - `instagramProfile` object, nullable — Instagram profile data for the participant. Only present for Instagram conversations.
      - `isFollower` boolean, nullable — Whether the participant follows your Instagram business account
      - `isFollowing` boolean, nullable — Whether your Instagram business account follows the participant
      - `followerCount` integer, nullable — The participant's follower count on Instagram
      - `isVerified` boolean, nullable — Whether the participant is a verified Instagram user
      - `fetchedAt` string, date-time, nullable — When this profile data was last fetched from Instagram
    - `metadata` object, nullable — Ad-click attribution for a conversation that started from a Meta ad. Absent when the conversation did not originate from an ad click. Captured from the referral Meta attaches to the first inbound message after the click, which is the only message that carries it. If the same person later clicks a different ad, the original values are kept, so the first ad wins. 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 and Facebook Messenger Click-to-Message. The ad ID is `meta_ad_id`. `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.
      - `ctwa_source_id` string — WhatsApp only. The Meta ad ID the user clicked. This is the WhatsApp equivalent of meta_ad_id.
      - `ctwa_source_type` string — WhatsApp only. What the user clicked, as supplied by Meta (for example ad or post).
      - `ctwa_source_url` string — WhatsApp only. Meta's URL for the ad that was clicked, normally an fb.me short link.
      - `ctwa_headline` string — WhatsApp only. Headline of the ad creative at click time.
      - `ctwa_captured_at` string, date-time — WhatsApp only. When Zernio stored this referral. Always present when a WhatsApp referral was captured.
      - `meta_ad_id` string — Instagram and Facebook only. The Meta ad ID the user clicked. Always present when an Instagram or Facebook referral was captured.
      - `meta_ad_source` string — Instagram and Facebook only. Meta-supplied source identifier, for example ADS.
      - `meta_ad_type` string — Instagram and Facebook only. Meta-supplied referral type, for example OPEN_THREAD.
      - `meta_ad_ref` string — Instagram and Facebook only. The ref parameter passed through from the ad creative.
      - `meta_ad_title` string — Instagram and Facebook only. Title of the ad creative at click time.
      - `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_post_id` string — Instagram and Facebook only. The organic post the ad promoted, when the ad was a boosted post.
      - `meta_ad_product_id` string — Instagram and Facebook only. The catalogue product the user clicked, for product ads.
      - `meta_ad_flow_id` string — Instagram and Facebook only. The Meta flow the ad launched, for flow 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.
  - `pagination` object
    - `hasMore` boolean
    - `nextCursor` string, nullable
  - `meta` object
    - `accountsQueried` integer
    - `accountsFailed` integer
    - `failedAccounts` object[]
      - `accountId` string
      - `accountUsername` string, nullable
      - `platform` string
      - `error` string
      - `code` string, nullable — Error code if available
      - `retryAfter` integer, nullable — Seconds to wait before retry (rate limits)
    - `lastUpdated` string, date-time

## Other responses

- `401` — Unauthorized
- `403` — Inbox addon required

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/versions/f81ca70ea6b9/schema)