> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List external conversation messages

> Requires `conversations:read`. Returns customer-facing user and assistant messages in newest-first order. Internal system and tool activity is excluded. Use `conversation.needsReply` from conversation metadata as the authoritative operator-action signal.



## OpenAPI

````yaml /openapi.json get /conversations/{conversationId}/messages
openapi: 3.0.3
info:
  title: Visito M2M API
  version: 1.0.0
  description: >-
    Tenant-scoped server-to-server API for channels, conversations, commerce,
    custom AI tools, and WhatsApp templates. Send operations are asynchronous
    and return queued acknowledgements. Expansion adds conversation controls,
    knowledge, sales opportunities, delivery status, reporting, and signed
    webhooks.
servers:
  - url: https://platform-api.visitoai.com/m2m/v1
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Channels
  - name: Conversations
  - name: Commerce
  - name: Custom tools
  - name: WhatsApp templates
  - name: Properties
  - name: Knowledge
  - name: Sales CRM
  - name: Delivery
  - name: Reporting
  - name: Webhooks
paths:
  /conversations/{conversationId}/messages:
    get:
      tags:
        - Conversations
      summary: List external conversation messages
      description: >-
        Requires `conversations:read`. Returns customer-facing user and
        assistant messages in newest-first order. Internal system and tool
        activity is excluded. Use `conversation.needsReply` from conversation
        metadata as the authoritative operator-action signal.
      operationId: listConversationMessages
      parameters:
        - $ref: '#/components/parameters/ConversationId'
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 200
            default: 50
        - name: cursor
          in: query
          description: >-
            Opaque, conversation-bound cursor from the previous response.
            Retrieves older messages.
          schema:
            type: string
      responses:
        '200':
          description: Newest-first page of external conversation messages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessagesResponse'
        '400':
          description: Invalid limit or malformed or conversation-mismatched cursor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Conversation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        default:
          $ref: '#/components/responses/Error'
components:
  parameters:
    ConversationId:
      name: conversationId
      in: path
      required: true
      schema:
        type: string
  schemas:
    ConversationMessagesResponse:
      type: object
      required:
        - conversationId
        - messages
        - nextCursor
        - hasMore
      properties:
        conversationId:
          type: string
        messages:
          type: array
          items:
            $ref: '#/components/schemas/ConversationMessage'
        nextCursor:
          type: string
          nullable: true
          description: >-
            Opaque cursor for the next older page, or null when hasMore is
            false.
        hasMore:
          type: boolean
          description: True when older external messages remain.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              example: M2M_AUTH_INSUFFICIENT_SCOPE
            message:
              type: string
            details:
              type: object
              additionalProperties: true
      example:
        error:
          code: M2M_AUTH_INSUFFICIENT_SCOPE
          message: M2M credential does not have required scope.
          details:
            requiredScopes:
              - conversations:write
            missingScopes:
              - conversations:write
    ConversationMessage:
      type: object
      required:
        - messageId
        - direction
        - role
        - text
        - createdAt
        - status
        - author
        - media
      properties:
        messageId:
          type: string
        eventId:
          type: string
          description: Matches `requestEventId` from a queued send response.
        externalMessageId:
          type: string
        direction:
          type: string
          enum:
            - inbound
            - outbound
        role:
          type: string
          enum:
            - user
            - assistant
        text:
          type: string
        createdAt:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - received
            - queued
            - sent
            - delivered
            - read
            - failed
            - blocked
            - partial_sent
            - unknown
        statusReason:
          type: string
        author:
          type: object
          required:
            - type
          properties:
            type:
              type: string
              enum:
                - user
                - ai
                - operator
                - system
                - native_channel
            operatorId:
              type: string
            operatorName:
              type: string
            displayName:
              type: string
        senderId:
          type: string
        recipientId:
          type: string
        replyTo:
          type: object
          additionalProperties: true
        media:
          type: array
          items:
            type: object
            additionalProperties: true
        deliveries:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: false
  responses:
    Error:
      description: Structured error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Visito M2M API key
      description: Server-side tenant-scoped credential created from Build > API Keys.

````