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

# Conversations

> Read chatbot conversations and their messages

## Overview

Conversations are read-only AI Career Chat sessions belonging to a chatbot. Each conversation has an ordered list of messages. List conversations for a chatbot, fetch a single conversation, and page through its messages with cursor pagination keyed on `sequenceOrder`.

<Note>
  Message `content` is free text authored by the candidate and may contain
  personal information they entered into the chat. Handle it accordingly.
</Note>

## List Chatbot Conversations

List the conversations for a chatbot (page paginated, newest first).

**Endpoint:** `GET /qsi/gather/chatbots/{chatbotId}/conversations`

<ParamField path="chatbotId" type="string" required>
  UUID of the chatbot
</ParamField>

<ParamField query="page" type="number">
  Page number (default: 1)
</ParamField>

<ParamField query="pageSize" type="number">
  Items per page (default: 50)
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "conversations": [
        {
          "id": "conv-uuid",
          "status": "ACTIVE",
          "startedAt": "2026-01-01T00:00:00Z",
          "endedAt": "2026-01-01T00:10:00Z",
          "candidateProfileId": "cp-uuid",
          "chatId": "chatbot-uuid",
          "organizationId": "org-uuid",
          "teamId": "team-uuid",
          "createdAt": "2026-01-01T00:00:00Z",
          "updatedAt": "2026-01-01T00:10:00Z"
        }
      ],
      "pagination": { "total": 3, "page": 1, "totalPages": 1, "pageSize": 50 }
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```
</CodeGroup>

A chatbot with no sessions returns `200` with an empty `conversations` array.

## Get Conversation

Retrieve a single conversation.

**Endpoint:** `GET /qsi/gather/conversations/{conversationId}`

<ParamField path="conversationId" type="string" required>
  UUID of the conversation
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "conversation": {
        "id": "conv-uuid",
        "status": "ENDED",
        "startedAt": "2026-01-01T00:00:00Z",
        "endedAt": "2026-01-01T00:10:00Z",
        "candidateProfileId": "cp-uuid",
        "chatId": "chatbot-uuid",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-01T00:10:00Z"
      }
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```
</CodeGroup>

`status` is one of `ACTIVE`, `ENDED`, or `ARCHIVED`.

## List Conversation Messages

Page through a conversation's messages in order, using cursor pagination on `sequenceOrder`.

**Endpoint:** `GET /qsi/gather/conversations/{conversationId}/messages`

<ParamField path="conversationId" type="string" required>
  UUID of the conversation
</ParamField>

<ParamField query="cursor" type="number">
  Return messages with `sequenceOrder` greater than this value. Omit for the first page.
</ParamField>

<ParamField query="limit" type="number">
  Page size (default: 50, max: 100)
</ParamField>

<CodeGroup>
  ```json Response theme={null}
  {
    "data": {
      "items": [
        {
          "id": "msg-uuid",
          "role": "USER",
          "content": "Do you have any remote roles?",
          "sequenceOrder": 1,
          "metadata": { "uiType": "TEXT" },
          "conversationId": "conv-uuid",
          "createdAt": "2026-01-01T00:00:01Z",
          "updatedAt": "2026-01-01T00:00:01Z"
        }
      ],
      "nextCursor": null
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```
</CodeGroup>

<Note>
  Messages use **cursor pagination**, not page-based pagination — the response
  contains `nextCursor` instead of a `pagination`/`total` object. Pass the
  returned `nextCursor` as the next request's `cursor` to fetch the following
  page. When `nextCursor` is `null`, there are no more messages. `role` is one
  of `USER`, `ASSISTANT`, or `SYSTEM`.
</Note>

## Error Responses

Errors use the standard envelope: a nested `error` object (`code`, `message`, and an optional `details`) alongside a `meta` block.

<CodeGroup>
  ```json 401 Unauthorized theme={null}
  {
    "error": {
      "code": "UNAUTHORIZED",
      "message": "Missing or invalid API key"
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```

  ```json 404 Not Found theme={null}
  {
    "error": {
      "code": "NOT_FOUND",
      "message": "Conversation not found"
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```

  ```json 500 Internal Server Error theme={null}
  {
    "error": {
      "code": "INTERNAL_ERROR",
      "message": "Failed to retrieve conversation"
    },
    "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
  }
  ```
</CodeGroup>

## Related Resources

<CardGroup cols={2}>
  <Card title="Chatbots" icon="robot" href="/api-reference/chatbots">
    Manage chatbots and configuration
  </Card>

  <Card title="Analytics" icon="chart-line" href="/api-reference/analytics">
    Chatbot engagement and funnel metrics
  </Card>
</CardGroup>