# 查询消息已读信息

查询指定消息是否已读。接口只返回已读用户的信息，不返回未读用户的信息。

## 前提条件
- 应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)  。
- 查询消息已读信息时，机器人需要在待查询消息所在的会话内。

## 使用限制
- 只能查询由当前机器人自己发送的、发送时间不超过 7 天的消息已读信息。
- 一次请求只能查询一条消息，不支持批量查询。

## 请求

基本 |  
---|---
HTTP URL | https://open.feishu.cn/open-apis/im/v1/messages/:message_id/read_users
HTTP Method | GET
接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN)
支持的应用类型 | Custom App、Store App
权限要求<br>**调用该 API 所需的权限。开启其中任意一项权限即可调用**<br>开启任一权限即可 | 获取与发送单聊、群组消息(im:message)<br>获取单聊、群组消息(im:message:readonly)<br>获取消息的基础信息V2(im:message:basic)
字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请<br>获取用户 user ID(contact:user.employee_id:readonly)

### 请求头

名称 | 类型 | 必填 | 描述
---|---|---|---
Authorization | string | 是 | `tenant_access_token`<br>**值格式**："Bearer `access_token`"<br>**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"<br>[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use)

### 路径参数

名称 | 类型 | 描述
---|---|---
message_id | string | 待查询的消息 ID。ID 获取方式：<br>- 调用[发送消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create)接口后，从响应结果的 `message_id` 参数获取。<br>- 监听[接收消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/events/receive)事件，当触发该事件后可以从事件体内获取消息的 `message_id`。<br>- 调用[获取会话历史消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/list)接口，从响应结果的 `message_id` 参数获取。<br>**示例值**："om_dc13264520392913993dd051dba21dcf"

### 查询参数

名称 | 类型 | 必填 | 描述
---|---|---|---
user_id_type | string | 是 | 用户 ID 类型<br>**示例值**：open_id<br>**可选值有**：<br>- open_id：标识一个用户在某个应用中的身份。同一个用户在不同应用中的 Open ID 不同。[了解更多：如何获取 Open ID](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-openid)<br>- union_id：标识一个用户在某个应用开发商下的身份。同一用户在同一开发商下的应用中的 Union ID 是相同的，在不同开发商下的应用中的 Union ID 是不同的。通过 Union ID，应用开发商可以把同个用户在多个应用中的身份关联起来。[了解更多：如何获取 Union ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-union-id)<br>- user_id：标识一个用户在某个租户内的身份。同一个用户在租户 A 和租户 B 内的 User ID 是不同的。在同一个租户内，一个用户的 User ID 在所有应用（包括商店应用）中都保持一致。User ID 主要用于在不同的应用间打通用户数据。[了解更多：如何获取 User ID？](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-obtain-user-id)<br>**默认值**：`open_id`<br>**当值为 `user_id`，字段权限要求**：<br>获取用户 user ID(contact:user.employee_id:readonly)
page_size | int | 否 | 分页大小，用于限制单次请求所返回的数据条目数。<br>**示例值**：20<br>**数据校验规则**：<br>- 取值范围：`1` ～ `100`
page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果<br>**示例值**：GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ==

## 响应

### 响应体

名称 | 类型 | 描述
---|---|---
code | int | 错误码，非 0 表示失败
msg | string | 错误描述
data | \- | \-
items | read_user\[\] | -
user_id_type | string | 用户id类型
user_id | string | 用户 ID，ID 类型与查询参数 user_id_type 取值一致。
timestamp | string | 已读消息的时间，毫秒级时间戳。
tenant_key | string | 租户唯一标识。该标识用来识别租户，也可以用来获取租户访问凭证（tenant_access_token）。
has_more | boolean | 是否还有更多项
page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token

### 响应体示例
```json
{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "user_id_type": "open_id",
                "user_id": "ou_9b851f7b51a9d58d109982337c46f3de",
                "timestamp": "1609484183000",
                "tenant_key": "736588c9260f175e"
            }
        ],
        "has_more": true,
        "page_token": "GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ=="
    }
}
```

### 错误码

HTTP状态码 | 错误码 | 描述 | 排查建议
---|---|---|---
400 | 230001 | Your request contains an invalid request parameter. | 参数错误，可根据接口实际返回的错误信息，并参考接口文档内容，检查输入参数是否填写错误。
400 | 230002 | The bot can not be outside the group. | 机器人不在对应群组中。你需要将应用机器人添加到接收消息的群组中。如何添加机器人参考[机器人使用指南](https://open.feishu.cn/document/ukTMukTMukTM/uATM04CMxQjLwEDN)。
400 | 230006 | Bot ability is not activated. | 应用未启用机器人能力。启用方式参见[如何启用机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。
400 | 230012 | Bot is NOT the sender of the message. | 当前机器人不是消息的发送者。应用机器人只能操作自己发送的消息。
400 | 230013 | Bot has NO availability to this user. | 目标用户（以用户的 user_id/open_id/union_id/email 指定的消息接收者）或单聊用户（以群聊的 chat_id 指定的消息接收者，但 chat_id 对应的群聊类型为单聊 `p2p`）不在应用机器人的可用范围内，或者是在应用的禁用范围内。<br>**注意**：如果目标用户已离职，也会报错 230013。<br>解决方案：<br>1. 登录[开发者后台](https://open.feishu.cn/app)，找到并进入指定应用详情页。<br>2. 在左侧导航栏进入 **应用发布** >  **版本管理与发布** 页面，点击 **创建版本**。<br>3. 在 **版本详情** 页面，找到 **可用范围** 区域，点击 **编辑**。<br>4. 在弹出的对话框内，配置应用的可用范围，将用户添加至可用范围内。<br>5. 在页面底部点击 **保存**，并发布应用使配置生效。<br>6. （可选）如果以上配置完成后仍报错，则需要联系企业管理员登录[管理后台](https://feishu.cn/admin)，在 **工作台** > **应用管理** 中进入指定应用详情页，在 **应用可用范围** 内查看该用户是否被设置为了 **禁用成员**。<br>具体操作参见[配置应用可用范围](https://open.feishu.cn/document/home/introduction-to-scope-and-authorization/availability)。
400 | 230027 | Lack of necessary permissions. | 无权进行本次操作。可能的原因有：<br>1. 缺少相应权限，可根据实际的错误信息进行排查。<br>2. 未检查到用户授权信息。<br>3. 暂不支持在外部群中进行本操作。
400 | 230033 | Get the reading status must be done within 7 days after the message is sent. | 在消息发送后的 7 天内允许查询消息的读取情况，超过 7 天则无法查询。
400 | 230110 | Action unavailable as the message has been deleted. | 消息已删除，无法执行操作。

更多错误码信息，参见[通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。