---
title: "List conversations with cursor pagination"
method: GET
path: "/conversations"
tags: ["Conversations"]
---

# List conversations with cursor pagination

`GET /conversations`

## Request

- Base URL: `https://platform-api.visitoai.com/m2m/v1`
- URL: `https://platform-api.visitoai.com/m2m/v1/conversations`
- Auth: HTTP bearer

Use to find a guest conversation or sample common topics across the inbox. Search stored guest identity with contactQuery and channel; participant.displayName and optional participant.phone identify the contact. list_assignable_operators lists staff, not guests. For exports defined by executed actions, use actionId and optional actionStatus before reading messages. Filters match saved projected action history; rows remain ordered by lastMessageAt, not latest action time. Query each desired action ID and deduplicate conversationId when combining results. For actions executed in a specific period use list_action_executions with from/to; missing projected history does not prove no action ran. This is not message-text search or an account-wide topic report. Requires `conversations:read`. Pass nextCursor as cursor with the same filters while hasMore is true. Ordered by lastMessageAt descending, then conversationId ascending. This is a live list, not a frozen snapshot; new activity can move a conversation ahead of a previously read boundary. Invalid cursors return 400 M2M_INVALID_REQUEST. Optional conversation.aiSummary describes main topics and current state. Read summaries first; fetch messages when the summary is absent, isStale is true, or supporting detail is needed. Summaries do not replace authoritative needsReply, booking, payment or delivery fields.

## Query parameters

- `limit` integer
- `cursor` string
- `view` 'all' | 'needs_reply' | 'handoff'
- `replyState` 'all' | 'failed'
- `policyStatus` 'all' | 'active' | 'archived' | 'blocked'
- `responseMode` 'all' | 'ai' | 'manual' | 'frozen'
- `optedOut` boolean
- `contactQuery` string
- `channel` 'all' | 'whatsapp' | 'instagram' | 'messenger' | 'tiktok' | 'webchat'
- `owner` string
- `actionId` string
- `actionStatus` 'all' | 'running' | 'completed' | 'failed'

## Response `200`

Conversation page with hasMore and optional nextCursor

- ConversationsResponse
  - `conversations` Conversation[], required
    - `conversationId` string, required
    - `conversationKey` string
    - `tenantId` string, required
    - `channel` 'whatsapp' | 'instagram' | 'messenger' | 'tiktok' | 'webchat', required
    - `participant` ConversationParticipant, required
      - `id` string, required
      - `displayName` string
      - `email` string
      - `phone` string
      - `username` string
      - `avatarUrl` string, uri
      - `updatedAt` string, date-time
    - `unreadCount` integer, required
    - `needsReply` boolean, required
    - `lastMessageAt` string, date-time, required
    - `lastMessageText` string, required
    - `lastMessageRole` string, required
    - `latestReplyStatus` 'queued' | 'sent' | 'failed' | 'blocked' | 'publish_failed'
    - `policyStatus` 'active' | 'waiting_tool' | 'handoff_requested' | 'closed' | 'archived' | 'blocked'
    - `responseMode` 'ai' | 'manual' | 'frozen'
    - `messageCount` integer, required
    - `frozenUntilAt` string, date-time: Optional timed AI pause expiry. Absence means no stored timer; a past timestamp is expired. Other policy restrictions may still prevent AI replies.
    - `needsReplySince` string, date-time
    - `needsReplyReason` string
    - `needsReplyDetail` string
    - `unreadUpdatedAt` string, date-time
    - `handoffStatus` 'none' | 'requested' | 'active' | 'resolved'
    - `activeHandoffCaseId` string
    - `handoffRequestedAt` string, date-time
    - `handoffResolvedAt` string, date-time
    - `handoffReasonCode` string
    - `handoffReasonDetail` string
    - `handoffIntentId` string
    - `handoffTitleKey` string
    - `handoffTitleFallback` string
    - `handoffOperatorNote` string
    - `handoffPropertyId` string
    - `handoffPropertyDisplayName` string
    - `handoffSeverity` 'hard' | 'soft'
    - `handoffCapturedFieldsDisplay` object[]
      - `id` string
      - `label` string
      - `value` string
    - `handoffMissingFieldsDisplay` object[]
      - `id` string
      - `label` string
    - `reviewStatus` 'none' | 'requested' | 'resolved' | 'cancelled'
    - `activeReviewCaseId` string
    - `reviewReasonCode` string
    - `reviewNote` string
    - `reviewRequestedAt` string, date-time
    - `reviewResolvedAt` string, date-time
    - `assignedOperatorId` string
    - `assignedOperatorName` string
    - `assignedAt` string, date-time
    - `latestReplyAt` string, date-time
    - `manualEnabled` boolean
    - `optedOut` boolean
    - `optedOutAt` string, date-time
    - `optedOutReason` 'user_stop'
    - `lastMessageEventId` string
    - `senderId` string
    - `recipientId` string
    - `handoffAvailability` HandoffAvailability
      - `status` 'within_hours' | 'outside_hours' | 'not_configured'
      - `timezone` string
      - `evaluatedAtLocal` string
      - `currentWindow` object
        - `date` string
        - `day` string
        - `start` string
        - `end` string
      - `nextWindow` object
        - `date` string
        - `day` string
        - `start` string
        - `end` string
    - `aiSummary` ConversationAiSummary
      - `text` string, required: Main topics and current state in one short paragraph; claims are informational.
      - `generatedAt` string, date-time, required
      - `throughMessageAt` string, date-time, required: Timestamp of the latest external message included in the summary.
      - `isStale` boolean, required: True while newer activity or incomplete history awaits processing.
  - `needsReplyCount` integer, required
  - `handoffCount` integer, required
  - `nextCursor` string
  - `hasMore` boolean, required
  - `asOf` string, date-time, required
  - `version` integer, required
  - `liveWindow` object, required
    - `limit` integer, required
    - `maxRows` integer, required
    - `mode` 'first_page_realtime' | 'cursor_page', required

## Other responses

- `default`: Structured error

---

[API](https://skmtc.dev/visitoai/apis/visito-m2m-api.md) - [All operations](https://skmtc.dev/visitoai/apis/visito-m2m-api/llms.txt) - [OpenAPI document](https://skmtc.dev/visitoai/apis/visito-m2m-api/revisions/98377d35c234?raw)