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

# Conversation Messages History

> List agent conversation messages

## 获取对话消息列表

**URL:** `/v1/agent/conversations/{conversation_id}/messages`\
**方法:** `GET`\
**描述:** 获取指定对话的消息列表，支持分页查询。

### 路径参数

| 参数名              | 类型      | 必填 | 描述    |
| ---------------- | ------- | -- | ----- |
| conversation\_id | integer | 是  | 对话 ID |

### 查询参数

| 参数名                 | 类型      | 必填 | 默认值 | 描述                     |
| ------------------- | ------- | -- | --- | ---------------------- |
| limit               | integer | 否  | 10  | 返回的消息数量（最小值：1，最大值：100） |
| before\_message\_id | integer | 否  | -   | 获取此消息 ID 之前创建的消息       |

### 响应参数

| 参数名      | 类型    | 描述             |
| -------- | ----- | -------------- |
| messages | array | 消息列表，每个元素为消息对象 |

#### 消息对象结构

| 参数名                    | 类型      | 描述                     |
| ---------------------- | ------- | ---------------------- |
| id                     | integer | 消息 ID                  |
| user\_id               | integer | 用户 ID                  |
| conversation\_id       | integer | 对话 ID                  |
| turn\_id               | integer | 对话轮次 ID                |
| role                   | string  | 消息角色（user 或 assistant） |
| reply\_to\_message\_id | integer | 回复的消息 ID（可为 null）      |
| content                | object  | 消息内容（可为 null）          |
| status                 | string  | 消息状态                   |
| error\_info            | object  | 错误信息（可为 null）          |
| assistant\_message\_id | string  | 助手消息 ID（可为 null）       |
| created\_at            | integer | 创建时间戳（毫秒）              |
| updated\_at            | integer | 更新时间戳（毫秒）              |
| assistant\_events      | array   | 助手事件列表（可为 null）        |

### 示例代码

#### cURL 示例

```bash theme={null}
curl -X GET "https://api.reportify.cn/v1/agent/conversations/683242877840089/messages?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### cURL 示例（分页查询）

```bash theme={null}
curl -X GET "https://api.reportify.cn/v1/agent/conversations/683242877840089/messages?limit=20&before_message_id=12345" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

#### Python 示例

```python theme={null}
import requests

url = "https://api.reportify.cn/v1/agent/conversations/683242877840089/messages"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}
params = {
    "limit": 20
}

response = requests.get(url, headers=headers, params=params)
data = response.json()

for message in data['messages']:
    print(f"消息 ID: {message['id']}, 角色: {message['role']}")
```

#### Python 示例（分页查询）

```python theme={null}
import requests

url = "https://api.reportify.cn/v1/agent/conversations/683242877840089/messages"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# 获取第一页
params = {"limit": 20}
response = requests.get(url, headers=headers, params=params)
data = response.json()

# 获取下一页（使用最后一条消息的 ID）
if data['messages']:
    last_message_id = data['messages'][-1]['id']
    params = {"limit": 20, "before_message_id": last_message_id}
    response = requests.get(url, headers=headers, params=params)
    next_page = response.json()
```

### 响应示例

```json theme={null}
{
  "messages": [
    {
      "id": 12346,
      "user_id": 987654321,
      "conversation_id": 683242877840089,
      "turn_id": 1,
      "role": "assistant",
      "reply_to_message_id": 12345,
      "content": {
        "text": "根据最新的财报数据，NVIDIA Q4 2024表现强劲..."
      },
      "status": "completed",
      "error_info": null,
      "assistant_message_id": "019b24ef238cc97730971a9a0080c99c",
      "created_at": 1765851195768,
      "updated_at": 1765851210657,
      "assistant_events": null
    },
    {
      "id": 12345,
      "user_id": 987654321,
      "conversation_id": 683242877840089,
      "turn_id": 1,
      "role": "user",
      "reply_to_message_id": null,
      "content": {
        "text": "nvidia 最新业绩分析"
      },
      "status": "completed",
      "error_info": null,
      "assistant_message_id": null,
      "created_at": 1765851195760,
      "updated_at": 1765851195760,
      "assistant_events": null
    }
  ]
}
```

### 注意事项

* 消息按创建时间倒序排列（最新的消息在前）
* 使用 `before_message_id` 参数可以实现向前翻页
* `limit` 参数的有效范围为 1-100
* 建议每次请求不超过 50 条消息，以获得更好的性能


## OpenAPI

````yaml GET /v1/agent/conversations/{conversation_id}/messages
openapi: 3.1.0
info:
  title: Reportify API
  version: 1.0.0
  description: API documentation for Reportify's document management and search services.
servers:
  - url: https://api.reportify.cn
    description: Production server
security:
  - BearerAuth: []
paths:
  /v1/agent/conversations/{conversation_id}/messages:
    get:
      tags:
        - openapi-agent
      summary: List Conversation Messages
      description: List agent conversation messages
      operationId: >-
        list_conversation_messages_reportify_api_v1_agent_conversations__conversation_id__messages_get
      parameters:
        - required: true
          schema:
            type: integer
            title: Conversation Id
            description: 对话 ID
          name: conversation_id
          in: path
          example: 683242877840089
        - required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            title: Limit
            description: Number of messages to return
            default: 10
          name: limit
          in: query
          description: 返回的消息数量
          example: 10
        - required: false
          schema:
            type: integer
            title: Before Message Id
            description: Fetch messages created before this message id
          name: before_message_id
          in: query
          description: 获取此消息 ID 之前创建的消息
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/OAIAgentConversationMessageRead'
                    description: 消息列表
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - BearerAuth: []
components:
  schemas:
    OAIAgentConversationMessageRead:
      properties:
        id:
          type: integer
          title: Id
          description: 消息 ID
          example: 12345
        user_id:
          type: integer
          title: User Id
          description: 用户 ID
          example: 987654321
        conversation_id:
          type: integer
          title: Conversation Id
          description: 对话 ID
          example: 683242877840089
        turn_id:
          type: integer
          title: Turn Id
          description: 对话轮次 ID
          example: 1
        role:
          type: string
          title: Role
          description: 消息角色（user 或 assistant）
          example: user
        reply_to_message_id:
          type: integer
          title: Reply To Message Id
          description: 回复的消息 ID
          nullable: true
          example: null
        content:
          type: object
          title: Content
          description: 消息内容
          nullable: true
          example:
            text: nvidia 最新业绩分析
        status:
          type: string
          title: Status
          description: 消息状态
          example: completed
        error_info:
          type: object
          title: Error Info
          description: 错误信息
          nullable: true
          example: null
        assistant_message_id:
          type: string
          title: Assistant Message Id
          description: 助手消息 ID
          nullable: true
          example: null
        created_at:
          type: integer
          title: Created At
          description: 创建时间戳（毫秒）
          example: 1765851195760
        updated_at:
          type: integer
          title: Updated At
          description: 更新时间戳（毫秒）
          example: 1765851195760
        assistant_events:
          type: array
          items:
            type: object
          title: Assistant Events
          description: 助手事件列表
          nullable: true
          example: null
      type: object
      required:
        - id
        - user_id
        - conversation_id
        - turn_id
        - role
        - status
        - created_at
        - updated_at
      title: OAIAgentConversationMessageRead
      description: Agent 对话消息
      example:
        id: 12345
        user_id: 987654321
        conversation_id: 683242877840089
        turn_id: 1
        role: user
        reply_to_message_id: null
        content:
          text: nvidia 最新业绩分析
        status: completed
        error_info: null
        assistant_message_id: null
        created_at: 1765851195760
        updated_at: 1765851195760
        assistant_events: null
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Enter your Bearer token

````