# 获取会话历史消息 获取指定会话（包括单聊、群组）内的历史消息（即聊天记录）。 ## 前提条件 - 应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability)。 - 获取消息时，机器人必须在被查询的群组中。 ## 请求 基本 |   ---|--- HTTP URL | https://open.feishu.cn/open-apis/im/v1/messages HTTP Method | GET 接口频率限制 | [1000 次/分钟、50 次/秒](https://open.feishu.cn/document/ukTMukTMukTM/uUzN04SN3QjL1cDN) 支持的应用类型 | Custom App、Store App 权限要求
**调用该 API 所需的权限。开启其中任意一项权限即可调用**
开启任一权限即可 | 获取与发送单聊、群组消息(im:message)
获取单聊、群组消息(im:message:readonly)
获取单聊、群组的历史消息(im:message.history:readonly)
**注意事项**：开启以上权限默认只能获取单聊（p2p）消息。如果你需要获取群组（group）消息，应用还必须开启 **获取群组中所有消息**（im:message.group_msg） 权限。 ### 请求头 名称 | 类型 | 必填 | 描述 ---|---|---|--- Authorization | string | 是 | `tenant_access_token`
**值格式**："Bearer `access_token`"
**示例值**："Bearer t-7f1bcd13fc57d46bac21793a18e560"
[了解更多：如何选择与获取 access token](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-choose-which-type-of-token-to-use) ### 查询参数 名称 | 类型 | 必填 | 描述 ---|---|---|--- container_id_type | string | 是 | 容器类型。
**可选值有**：
- `chat`：包含单聊（p2p）和群聊（group）
- `thread`：话题
**注意**：对于 **普通对话群** 中的话题消息，通过 `chat` 容器类型仅能获取到话题的根消息，你可通过指定容器类型为 `thread` 获取话题回复中的所有消息。
**示例值**：chat container_id | string | 是 | 容器 ID。ID 类型与 container_id_type 取值一致。
- 群聊或单聊的 ID 获取方式参见[群 ID 说明](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat-id-description)。
- 话题 ID 获取参见[话题概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction)的 **如何获取 thread_id** 章节。
**示例值**：oc_234jsi43d3ssi993d43545f start_time | string | 否 | 待查询历史信息的起始时间，秒级时间戳。
**注意**：`thread` 容器类型暂不支持获取指定时间范围内的消息。
**示例值**：1608594809 end_time | string | 否 | 待查询历史信息的结束时间，秒级时间戳。
**注意**：`thread` 容器类型暂不支持获取指定时间范围内的消息。
**示例值**：1609296809 sort_type | string | 否 | 消息排序方式。
**注意**：使用 `page_token` 分页请求时，排序方式（`sort_type`）均与第一次请求一致，不支持中途改换排序方式。
**示例值**：ByCreateTimeAsc
**可选值有**：
- ByCreateTimeAsc：按消息创建时间升序排列
- ByCreateTimeDesc：按消息创建时间降序排列
**默认值**：`ByCreateTimeAsc` page_size | int | 否 | 分页大小，即单次请求所返回的数据条目数。
**示例值**：20
**默认值**：`20`
**数据校验规则**：
- 取值范围：`1` ～ `50` page_token | string | 否 | 分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
**示例值**：GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ== ## 响应 ### 响应体 名称 | 类型 | 描述 ---|---|--- code | int | 错误码，非 0 表示失败 msg | string | 错误描述 data | \- | \- has_more | boolean | 是否还有更多项 page_token | string | 分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token items | message\[\] | 历史消息数据。 message_id | string | 消息 ID，由系统生成的唯一 ID 标识。后续对消息的管理维护操作均需要使用该 ID。 root_id | string | 根消息 ID。在有多个回复的消息树中，`root_id` 为根消息的 `message_id`。如果回复的是话题，则 `root_id` 为话题内根消息的 `message_id`。关于 `root_id` 的更多说明，参见[消息管理概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro)。 parent_id | string | 父消息 ID。在有多个回复的消息树中，`parent_id` 为当前消息上一层的消息 `message_id`。如果回复的是话题，则 `parent_id` 始终为话题内根消息的 `message_id`。关于 `parent_id` 的更多说明，参见[消息管理概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro)。 thread_id | string | 消息所属的话题 ID（不返回说明该消息不是话题形式的消息）。了解话题可参见[话题概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction)。 msg_type | string | 消息类型。各类型详情参考[接收消息内容](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/events/message_content)。 create_time | string | 消息生成的时间戳。单位：毫秒 update_time | string | 消息更新的时间戳。单位：毫秒 deleted | boolean | 消息是否被撤回或删除。
- true：是，如果是被撤回的消息，content 参数固定返回 `This message was recalled`。
- false：否 updated | boolean | 消息是否被更新。
- true：是
- false：否 chat_id | string | 消息所属的群 ID。你可以调用[获取群信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get)接口，根据群 ID 获取群详情。 sender | sender | 当前消息的发送者信息。 id | string | 发送者的 ID。 id_type | string | 发送者的 ID 类型。
**可能值有：**
- `open_id`：表示发送者为用户，且返回的 ID 是用户的 open_id。
- `app_id`：表示发送者为应用，且返回的 ID 是应用的 app_id。 sender_type | string | 发送者类型。
**可能值有：**
- `user`: 用户
- `app`: 应用
- `anonymous`: 匿名
- `unknown`: 未知 tenant_key | string | 租户唯一标识。该标识用来识别租户，也可以用来获取租户访问凭证（tenant_access_token）。 body | message_body | 通过 `body` 内的 `content` 参数，返回当前的消息内容。 content | string | 消息内容，JSON 结构序列化后的字符串，不同消息类型（`msg_type`）对应不同内容。
**注意**：卡片消息内容与在卡片搭建工具中获取的卡片 JSON 不一致，暂不支持返回原始卡片 JSON mentions | mention\[\] | 消息内被 @ 的用户或机器人列表。 key | string | 被 @ 的用户或机器人序号。例如，第 3 个被 @ 到的成员，取值为 `@_user_3`。 id | string | 被 @ 的用户或机器人的 open_id。 id_type | string | 被 @ 的用户或机器人的 ID 类型，目前仅支持 `open_id` (了解[什么是 Open ID](https://open.feishu.cn/document/home/user-identity-introduction/open-id))。 name | string | 被 @ 的用户或机器人的姓名。 tenant_key | string | 租户唯一标识。该标识用来识别被 @ 用户或机器人的租户，也可以用来获取租户访问凭证（tenant_access_token）。 upper_message_id | string | 合并转发消息中，上一层级的消息 ID，仅在合并转发场景会有返回值。了解 upper_message_id 可参见[消息管理概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro)。 ### 响应体示例 ```json { "code": 0, "msg": "success", "data": { "has_more": false, "page_token": "GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ==", "items": [ { "message_id": "om_dc13264520392913993dd051dba21dcf", "root_id": "om_40eb06e7b84dc71c03e009ad3c754195", "parent_id": "om_d4be107c616aed9c1da8ed8068570a9f", "thread_id": "omt_d4be107c616a", "msg_type": "interactive", "create_time": "1615380573411", "update_time": "1615380573411", "deleted": false, "updated": false, "chat_id": "oc_5ad11d72b830411d72b836c20", "sender": { "id": "cli_9f427eec54ae901b", "id_type": "app_id", "sender_type": "app", "tenant_key": "736588c9260f175e" }, "body": { "content": "{\"text\":\"test content\"}" }, "mentions": [ { "key": "@_user_1", "id": "ou_155184d1e73cbfb8973e5a9e698e74f2", "id_type": "open_id", "name": "Tom", "tenant_key": "736588c9260f175e" } ], "upper_message_id": "om_40eb06e7b84dc71c03e009ad3c754195" } ] } } ``` ### 错误码 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 | 230027 | Lack of necessary permissions. | 无权进行本次操作。可能的原因有：
1. 缺少相应权限，可根据实际的错误信息进行排查。
2. 未检查到用户授权信息。
3. 如果需要机器人在外部群操作，则需要先为机器人开启对外共享能力，详情参见[机器人支持外部群和外部用户单聊](https://open.feishu.cn/document/uAjLw4CM/ukzMukzMukzM/develop-robots/add-bot-to-external-group)。 400 | 230073 | The thread is invisible to the operator. | 该话题对于当前操作者不可见。如果群聊关闭了 **新成员可查看历史消息** 且此话题为当前操作者进入群聊之前创建的，则该话题需要操作者被动订阅才可见（如其他用户在话题中@操作者）。 400 | 230110 | Action unavailable as the message has been deleted. | 消息已删除，无法执行操作。 其他未列出的错误码请参见[服务端通用错误码](https://open.feishu.cn/document/ukTMukTMukTM/ugjM14COyUjL4ITN)。