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

# List a conversation's messages

> Pages through the messages of a conversation's thread, oldest first (`limit`, default 100, at most 500; pass `next_cursor` back as `cursor` while `has_more`; a cursor from another conversation is a 400). Each says who wrote it (`role`: customer, user, digital_worker or system), which way it went (`direction`) and whether an AI wrote it (`ai_written`), with its sender, an email's recipients (never bcc) and subject, its text as stored, and its attachments by name. AI drafts no one has sent are not messages, and never appear. This reads the conversations' words: grant conversations:read only to an integration that may read them.



## OpenAPI

````yaml /api/statisfy-api.openapi.json get /v1/conversations/{conversation_id}/messages
openapi: 3.1.0
info:
  description: >-
    The agent-first Statisfy API. Authenticate with an API key (`Authorization:
    Bearer stfy_live_…`), then call `GET /v1/meta/capabilities` to discover
    every operation and its schemas.
  title: Statisfy API
  version: 1.0.0
servers:
  - url: https://api.statisfy.com
    description: Production
security: []
paths:
  /v1/conversations/{conversation_id}/messages:
    get:
      tags:
        - conversations
      summary: List a conversation's messages
      description: >-
        Pages through the messages of a conversation's thread, oldest first
        (`limit`, default 100, at most 500; pass `next_cursor` back as `cursor`
        while `has_more`; a cursor from another conversation is a 400). Each
        says who wrote it (`role`: customer, user, digital_worker or system),
        which way it went (`direction`) and whether an AI wrote it
        (`ai_written`), with its sender, an email's recipients (never bcc) and
        subject, its text as stored, and its attachments by name. AI drafts no
        one has sent are not messages, and never appear. This reads the
        conversations' words: grant conversations:read only to an integration
        that may read them.
      operationId: conversations_messages
      parameters:
        - description: The conversation's id, from GET /v1/conversations
          in: path
          name: conversation_id
          required: true
          schema:
            type: string
        - description: Messages per page
          in: query
          name: limit
          required: false
          schema:
            default: 100
            maximum: 500
            minimum: 1
            type: integer
        - description: '`next_cursor` from the previous page'
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: null
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationMessagePage'
          description: Successful Response
      security:
        - HTTPBearer: []
components:
  schemas:
    ConversationMessagePage:
      properties:
        data:
          description: The thread's messages, oldest first
          items:
            $ref: '#/components/schemas/ActivityMessage'
          title: Data
          type: array
        has_more:
          default: false
          title: Has More
          type: boolean
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
      required:
        - data
      title: ConversationMessagePage
      type: object
    ActivityMessage:
      properties:
        ai_written:
          default: false
          description: >-
            Whether an AI wrote it: a digital worker's message, or its draft a
            person sent. A reply a person wrote themselves is not, even when
            Stella suggested it
          title: Ai Written
          type: boolean
        attachments:
          description: Files sent with it, by name only
          items:
            $ref: '#/components/schemas/ActivityAttachment'
          title: Attachments
          type: array
        automated:
          anyOf:
            - type: string
            - type: 'null'
          description: bounce or auto_reply when a mail system sent it rather than a person
          title: Automated
        cc:
          items:
            type: string
          title: Cc
          type: array
        direction:
          anyOf:
            - enum:
                - inbound
                - outbound
              type: string
            - type: 'null'
          description: >-
            inbound (from the customer's side) or outbound (from the workspace);
            null when unknown
          title: Direction
        id:
          title: Id
          type: string
        role:
          anyOf:
            - enum:
                - customer
                - user
                - digital_worker
                - system
              type: string
            - type: 'null'
          description: >-
            Who wrote it: customer, user (a teammate), digital_worker (an AI),
            or system (a mail system's bounce or auto-reply, or the portal's or
            in-app chat's notice that a person will reply; on email, Slack and
            Teams that notice is the digital_worker's). Null when it can't be
            told: a sender who matched no person, one whose type is unset, or a
            message kept only as its source sent it
          title: Role
        sender:
          anyOf:
            - $ref: '#/components/schemas/ActivityMessageSender'
            - type: 'null'
        sent_at:
          anyOf:
            - type: string
            - type: 'null'
          description: ISO 8601 UTC
          title: Sent At
        subject:
          anyOf:
            - type: string
            - type: 'null'
          title: Subject
        text:
          description: The message's text, as stored when it was ingested
          title: Text
          type: string
        to:
          description: An email's recipients
          items:
            type: string
          title: To
          type: array
      required:
        - id
        - text
      title: ActivityMessage
      type: object
    ActivityAttachment:
      properties:
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
        mime_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Mime Type
        size_bytes:
          anyOf:
            - type: integer
            - type: 'null'
          title: Size Bytes
      title: ActivityAttachment
      type: object
    ActivityMessageSender:
      properties:
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
        id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            The person's id; null when it was stored without one: a sender who
            matched no person, a message kept only as its source sent it (a
            ticket's, Chatter's, an older email's), or a note Stella or a
            workflow wrote
          title: Id
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
        type:
          anyOf:
            - enum:
                - user
                - contact
                - vendor
                - digital_worker
              type: string
            - type: 'null'
          title: Type
      title: ActivityMessageSender
      type: object
  securitySchemes:
    HTTPBearer:
      scheme: bearer
      type: http
      description: >-
        An API key, sent as `Authorization: Bearer stfy_live_…`. See
        [Authentication](/rest-api/authentication) for how to get one and which
        scopes it needs.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.