---
title: "List external conversation messages"
method: GET
path: "/conversations/{conversationId}/messages"
tags: ["Conversations"]
---

# List external conversation messages

`GET /conversations/{conversationId}/messages`

## Request

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

Use to read what the guest and assistant said, including message types and stored media context. Discover conversationId with list_conversations. Use each stored messageId for get_message_status, get_conversation_attachment or, for an AI assistant answer, get_conversation_answer_trace. Action results are separate: use list_action_executions filtered by conversationId. Requires `conversations:read`. Returns customer-facing user and assistant messages in newest-first order, including shared locations, contacts, reactions, media, rendered cards/actions, referrals and delivery details when present. Pass nextCursor as cursor for older messages with the same conversationId; stop when hasMore is false. Internal system/tool activity is excluded. Use conversation.needsReply from metadata as the operator-action signal. Unknown delivery status is not delivery proof.

## Path parameters

- `conversationId` string, required

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

Newest-first page of external conversation messages

- ConversationMessagesResponse
  - `conversationId` string, required
  - `messages` ConversationMessage[], required
    - `messageId` string, required
    - `eventId` string: Matches `requestEventId` from a queued send response.
    - `externalMessageId` string
    - `direction` 'inbound' | 'outbound', required
    - `role` 'user' | 'assistant', required
    - `text` string, required
    - `createdAt` string, date-time, required
    - `status` 'received' | 'queued' | 'sent' | 'delivered' | 'read' | 'failed' | 'blocked' | 'partial_sent' | 'unknown', required
    - `statusReason` string
    - `author` object, required
      - `type` 'user' | 'ai' | 'operator' | 'system' | 'native_channel', required
      - `operatorId` string
      - `operatorName` string
      - `displayName` string
    - `senderId` string
    - `recipientId` string
    - `replyTo` object
    - `media` ConversationMessageMedia[], required
      - `attachmentIndex` integer
      - `type` string
      - `externalMediaId` string
      - `label` string
      - `contentType` string
      - `storageUrl` string
      - `transcriptText` string
      - `transcriptionStatus` string
      - `transcriptionError` string
      - `hasCaption` boolean
      - `processingStatus` 'unknown' | 'pending' | 'ready' | 'failed' | 'timed_out' | 'optional_failed': Stored processing outcome; legacy URLs infer ready, absence of an outcome or URL is unknown.
      - `processingReason` string
      - `processingAt` string, date-time
      - `processingTerminal` boolean
      - `mediaContextText` string
      - `mediaContextStatus` string
      - `mediaContextTruncated` boolean
    - `deliveries` object[]
    - `textOrigin` 'provider' | 'synthetic'
    - `providerErrorCode` number
    - `reaction` string
    - `reactionAt` string, date-time
    - `location` ConversationMessageLocation
      - `latitude` number
      - `longitude` number
      - `name` string
      - `address` string
    - `contacts` ConversationMessageContact[]
      - `displayName` string
      - `phones` object[]
        - `number` string
        - `label` string
      - `emails` object[]
        - `address` string
        - `label` string
    - `contactCount` integer
    - `contactsTruncated` boolean
    - `originalText` string
    - `adapterOutput` object
      - `text` string
      - `cards` ConversationOutputCard[]
        - `text` string
        - `media` ConversationOutputMedia
          - `mediaId` string
          - `type` string: Read-only media type. Canonical cards use image, video, audio or document; native/provider messages can use file, sticker or other attachment types. This does not expand accepted outbound media types.
          - `url` string
          - `contentType` string
          - `filename` string
          - `sizeBytes` integer
          - `caption` string
          - `voice` boolean
          - `requireNative` boolean
        - `actions` ConversationOutputAction[]
          - `id` string
          - `label` string
          - `kind` 'reply' | 'url'
          - `text` string
          - `url` string
          - `payload` object
    - `displayCards` ConversationOutputCard[]
      - `text` string
      - `media` ConversationOutputMedia
        - `mediaId` string
        - `type` string: Read-only media type. Canonical cards use image, video, audio or document; native/provider messages can use file, sticker or other attachment types. This does not expand accepted outbound media types.
        - `url` string
        - `contentType` string
        - `filename` string
        - `sizeBytes` integer
        - `caption` string
        - `voice` boolean
        - `requireNative` boolean
      - `actions` ConversationOutputAction[]
        - `id` string
        - `label` string
        - `kind` 'reply' | 'url'
        - `text` string
        - `url` string
        - `payload` object
    - `displayActions` ConversationOutputAction[]
      - `id` string
      - `label` string
      - `kind` 'reply' | 'url'
      - `text` string
      - `url` string
      - `payload` object
    - `referral` ConversationReferral
      - `type` 'meta_ad' | 'meta_post' | 'meta_referral'
      - `label` string
      - `sourceType` string
      - `sourceId` string
      - `sourceUrl` string
      - `ref` string
      - `adId` string
      - `source` string
      - `referralType` string
      - `headline` string
      - `body` string
      - `mediaType` string
      - `imageUrl` string
      - `videoUrl` string
      - `thumbnailUrl` string
      - `cachedThumbnailUrl` string
      - `cachedImageUrl` string
      - `mediaSummary` string
      - `mediaCacheStatus` string
      - `mediaCachedAt` string
      - `mediaCacheError` string
      - `welcomeText` string
      - `ctwaClid` string
      - `seenAt` string
    - `crmFollowUp` object
      - `followUpId` string
      - `mode` 'draft' | 'auto'
    - `inputType` string
    - `awaitingMedia` boolean
    - `mediaExpected` integer
    - `mediaReadyCount` integer
    - `mediaTimedOut` boolean
    - `interactive` object
      - `type` string
      - `name` string
      - `title` string
      - `id` string
      - `payload` unknown
      - `payloadTruncated` boolean
    - `interaction` object
      - `actionId` string
      - `label` string
      - `sourceTurnEventId` string
      - `cardIndex` integer
      - `resolved` boolean
      - `errorReason` string
  - `nextCursor` string, nullable, required: Opaque cursor for the next older page, or null when hasMore is false.
  - `hasMore` boolean, required: True when older external messages remain.

## Other responses

- `400`: Invalid limit or malformed or conversation-mismatched cursor
- `404`: Conversation not found
- `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)