> ## 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.

# Read conversation metadata

> Requires `conversations:read`. Returns metadata only. `conversation.needsReply` is the authoritative signal that operator action is required; `lastMessageRole` describes chronology only.



## OpenAPI

````yaml /openapi.json get /conversations/{conversationId}
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}:
    get:
      tags:
        - Conversations
      summary: Read conversation metadata
      description: >-
        Requires `conversations:read`. Returns metadata only.
        `conversation.needsReply` is the authoritative signal that operator
        action is required; `lastMessageRole` describes chronology only.
      operationId: getConversation
      parameters:
        - $ref: '#/components/parameters/ConversationId'
      responses:
        '200':
          description: Conversation detail
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMetadataResponse'
        '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:
    ConversationMetadataResponse:
      type: object
      required:
        - conversation
      properties:
        conversation:
          $ref: '#/components/schemas/Conversation'
    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
    Conversation:
      type: object
      required:
        - conversationId
        - tenantId
        - channel
        - participant
        - unreadCount
        - needsReply
        - lastMessageAt
        - lastMessageText
        - lastMessageRole
        - messageCount
      properties:
        conversationId:
          type: string
        conversationKey:
          type: string
        tenantId:
          type: string
        channel:
          type: string
          enum:
            - whatsapp
            - instagram
            - messenger
            - webchat
        participant:
          $ref: '#/components/schemas/ConversationParticipant'
        unreadCount:
          type: integer
        needsReply:
          type: boolean
        lastMessageAt:
          type: string
          format: date-time
        lastMessageText:
          type: string
        lastMessageRole:
          type: string
        latestReplyStatus:
          type: string
          enum:
            - queued
            - sent
            - failed
            - blocked
            - publish_failed
        policyStatus:
          type: string
          enum:
            - active
            - waiting_tool
            - handoff_requested
            - closed
            - archived
            - blocked
        responseMode:
          type: string
          enum:
            - ai
            - manual
            - frozen
        messageCount:
          type: integer
      additionalProperties: true
    ConversationParticipant:
      type: object
      required:
        - id
      properties:
        id:
          type: string
        displayName:
          type: string
        email:
          type: string
        phone:
          type: string
        username:
          type: string
        avatarUrl:
          type: string
          format: uri
  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.

````