---
title: "POST /message.query"
method: POST
path: "/message.query"
tags: ["message"]
---

# POST /message.query

`POST /message.query`

查询指定 vchannel 下的消息列表。支持以下几种查询算法：

### `latest`

查询 vchannel 下最新的消息，支持参数：

- `limit`: 查询数量限制，最大值为 100, 默认 20

### `since`

从指定位置开始拉取若干条消息，支持参数：

- `key`: 开始位置的消息 key, 不可以和 `ts` 同时使用
- `ts`: 开始位置的消息 ts, 不可以和 `ts` 同时使用
- `forward`: 向前（时间发生方向）获取条数
- `backward`: 向后（时间发生方向）获取条数

**注意**:

1. 使用 `key` 查询时，查询区间不包括 key 对应的消息
2. 使用 `ts` 查询时，查询区间包括 ts 对应的消息
3. `forward` / `backward` 参数可以同时使用
4. `forward` / `backward` 参数最大值为 100,
5. `forward` / `backward` 均未指定时，默认使用 `forward=100`

### `window`

拉取一定时间窗口内的消息，支持参数：

- `from_key` / `to_key`: 窗口区间的消息 key
- `from_ts` / `to_ts`: 窗口区间的消息 ts
- `forward`: 从 from 方向往 to 方向取的消息数
- `backward`: 从 to 方向往 from 方向取的消息数

**注意**:

1. `{from,to}_key` 和 `{from,to}_ts` 不可以混用
2. 使用 `{from,to}_key` 查询时，查询区间不包括 key 对应的消息
3. 使用 `{from,to}_ts` 查询时，查询区间包括 ts 对应的消息
4. `forward` 和 `backward` 参数只能选其中一个
5. `forward` / `backward` 均未指定时，默认使用 `forward=100`
6. 如果查询区间开始值比结束值大，返回空结果

## Request body

- object
  - `vchannel_id` string, required — 待查询 vchannel_id
  - `query` MessageQuery, required — window / since / latest / thread 只能存在其中一种查询方法 如果带有多种查询方法，则只以第一个方法为准
    - `window` MessageQueryWindow — 拉取一定时间窗口里面的消息 {from,to}_key / {from,to}_ts 不能混用，优先使用 {from,to}_key 对 from_{key,ts} to_{key,ts} 必须成对出现 使用消息 key 查询的时候，查询区间为 (from_key, to_key) 使用消息 ts 查询的时候，查询区间为 [from_ts, to_ts] forward / backward 可选其一 查询结果最多返回 100 条消息： - forward / backward 最大值为 100 - 不指定 forward / backward 时，默认返回 forward=100 的消息记录 - 如果查询区间开始值比结束值大，返回空结果
      - `form_key` string — 区间开始的消息 `key`
      - `to_key` string — 区间结束的消息 `key`
      - `from_ts` integer — 区间开始的消息时间戳
      - `to_ts` integer — 区间结束的消息时间戳
      - `forward` integer — 向前获取 n 条消息
      - `backward` integer — 向后获取 n 条消息
    - `since` MessageQuerySince — 从指定位置开始拉取若干条消息 key / ts 不能混用，优先使用 key forward / backward 可同时使用，默认为 forward=100 使用消息 key 查询的时候，查询区间为 (key, +inf) / (-inf, key) 使用消息 ts 查询的时候，查询区间为 [ts, +inf) / (-inf, ts] forward / backward 可选其一 查询结果最多返回 100 条消息： - forward / backward 最大值为 100 - 不指定 forward / backward 时，默认返回 forward=100 的消息记录 - 如果同时使用 forward / backward 查询，返回消息保证 总数 <= forward + backward
      - `key` string — 指定位置的消息 `key`
      - `ts` integer — 指定位置的消息时间戳
      - `forward` integer — 向前获取 n 条消息
      - `backward` integer — 向后获取 n 条消息
    - `latest` MessageQueryLatest — 获取该 vchannel 下的最新消息列表 查询结果最多返回 100 条消息： - limit 最大值为 100 - 不指定 limit 时，limit 默认为 20
      - `limit` integer — 获取 n 条消息

## Response `200`

request success

- MessageQueryResult
  - `messages` Message[], required — 查询到的消息列表
    - `key` string, required — 消息唯一索引 key
    - `team_id` string, required
    - `uid` string, required
    - `robot_id` string, required
    - `vchannel_id` string, required — 聊天会话 id
    - `refer_key` string, required — 消息唯一索引 key
    - `subtype` 'normal' | 'info', required — 消息类型
    - `text` string, required — 消息正文
    - `fallback` string, required — 消息提醒使用正文
    - `attachments` MessageAttachment[], required — 消息附件
    - `created` string, date-time, required — 消息创建时间
    - `created_ts` integer, required — 消息创建时间戳
    - `updated` string, date-time, required — 消息最后修改时间
    - `is_channel` boolean, required — 消息是否为讨论组消息？

## Other responses

- `default` — request fail

## Changes

- **2017-04-19** `fd4c7a508190` — 1 info
  - api tag `message` added
- **2017-04-18** `b37660ad33e5` — 1 info
  - api tag `message` removed
- **2017-04-04** `4751e3946b90` — 1 info
  - api tag `message` added
- **2017-03-13** `ef71aa691171` — 1 info
  - api tag `message` removed

[Change history](https://skmtc.dev/bearyinnovative/apis/beary-openapi/changes/message.query/post.md)

---

[API](https://skmtc.dev/bearyinnovative/apis/beary-openapi.md) · [All operations](https://skmtc.dev/bearyinnovative/apis/beary-openapi/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/bearyinnovative/beary-openapi/revisions/af2ef45fcabb/schema)