飞书开放平台 Server API 文档

主题

获取会话历史消息 ​

获取指定会话（包括单聊、群组）内的历史消息（即聊天记录）。

前提条件 ​

  • 应用需要开启机器人能力。
  • 获取消息时，机器人必须在被查询的群组中。

请求 ​

项目值
HTTP URLhttps://open.feishu.cn/open-apis/im/v1/messages
HTTP MethodGET
接口频率限制1000 次/分钟、50 次/秒
支持的应用类型custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可im:message 获取与发送单聊、群组消息 im:message:readonly 获取单聊、群组消息 im:message.history:readonly 获取单聊、群组的历史消息 > Tip: 1. 应用身份获取消息 > 1. 获取单聊消息 需要开启三个权限任意一个： 获取与发送单聊、群组消息（im:message）获取单聊、群组消息（im:message:readonly）获取单聊、群组的历史消息【历史版本】（im:message.history:readonly）。 > 2. 获取群聊消息 需先申请单聊场景的任一权限，此外应用还必须开启 获取群组中所有消息（im:message.group_msg） 权限。 > 2. 用户身份获取消息 > 1. 所有群类型都需要先 开启二个以下权限任意一个获取与发送单聊、群组消息（im:message）获取单聊、群组消息（im:message:readonly） > 2. 根据群类型额外开启补充权限： > 1. 获取单聊消息 需要开启以用户身份获取单聊消息（im:message.p2p_msg:get_as_user）权限 > 2. 获取群聊消息 需要开启以用户身份获取群聊消息（im:message.group_msg:get_as_user）权限

请求头 ​

名称类型必填描述
Authorizationstring是tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token

查询参数 ​

名称类型必填描述
container_id_typestring是容器类型。
可选值有： - chat：包含单聊（p2p）和群聊（group） - thread：话题
注意：对于 普通对话群 中的话题消息，通过 chat 容器类型仅能获取到话题的根消息，你可通过指定容器类型为 thread 获取话题回复中的所有消息。
示例值：chat
container_idstring是容器 ID。ID 类型与 container_id_type 取值一致。
- 群聊或单聊的 ID 获取方式参见群 ID 说明。 - 话题 ID 获取参见话题概述的 如何获取 thread_id 章节。
示例值：oc_234jsi43d3ssi993d43545f
start_timestring否待查询历史信息的起始时间，秒级时间戳。
注意：thread 容器类型暂不支持获取指定时间范围内的消息。
示例值：1608594809
end_timestring否待查询历史信息的结束时间，秒级时间戳。
注意：thread 容器类型暂不支持获取指定时间范围内的消息。
示例值：1609296809
sort_typestring否消息排序方式。
注意：使用 page_token 分页请求时，排序方式（sort_type）均与第一次请求一致，不支持中途改换排序方式。
示例值：ByCreateTimeAsc
可选值有：
- ByCreateTimeAsc: 按消息创建时间升序排列 - ByCreateTimeDesc: 按消息创建时间降序排列
默认值：ByCreateTimeAsc
page_sizeint否分页大小，即单次请求所返回的数据条目数。
示例值：20
默认值：20
数据校验规则：
- 取值范围：1 ～ 50
page_tokenstring否分页标记，第一次请求不填，表示从头开始遍历；分页查询结果还有更多项时会同时返回新的 page_token，下次遍历可采用该 page_token 获取查询结果
示例值：GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhUPhXQDvtrQ==
card_msg_content_typestring否card_msg_content_type 参数仅控制卡片消息的返回格式，不会影响其他类型消息的返回格式。
1. 不传该参数（默认）：返回的卡片结构参考接收消息内容中的卡片消息结构，不支持返回发送时的原始卡片 JSON。 2. 传入 user_card_content：返回发送时的原始卡片 JSON。1.0 卡片请参考卡片 JSON 1.0 结构；2.0 卡片请参考卡片 JSON 2.0 结构。 * 版本区分：当返回的消息体为卡片时，可通过 schema 字段来区分该卡片是 1.0 还是 2.0 版本，详情参考卡片 JSON 2.0 版本更新说明。
> 注意：如果 card_msg_content_type 参数的传值方式发生变更，请务必在代码中做好返回格式的兼容处理。
示例值：user_card_content

响应 ​

响应体 ​

名称类型描述
codeint错误码，非 0 表示失败
msgstring错误描述
data\--
  └ has_moreboolean是否还有更多项
  └ page_tokenstring分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token
  └ itemsmessage\[\]历史消息数据。
    └ message_idstring消息 ID，由系统生成的唯一 ID 标识。后续对消息的管理维护操作均需要使用该 ID。
    └ root_idstring根消息 ID。在有多个回复的消息树中，root_id 为根消息的 message_id。如果回复的是话题，则 root_id 为话题内根消息的 message_id。关于 root_id 的更多说明，参见消息管理概述。
    └ parent_idstring父消息 ID。在有多个回复的消息树中，parent_id 为当前消息上一层的消息 message_id。如果回复的是话题，则 parent_id 始终为话题内根消息的 message_id。关于 parent_id 的更多说明，参见消息管理概述。
    └ thread_idstring消息所属的话题 ID（不返回说明该消息不是话题形式的消息）。了解话题可参见话题概述。
    └ msg_typestring消息类型。各类型详情参考接收消息内容。
    └ create_timestring消息生成的时间戳。单位：毫秒
    └ update_timestring消息更新的时间戳。单位：毫秒
    └ deletedboolean消息是否被撤回或删除。
- true：是，如果是被撤回的消息，content 参数固定返回 This message was recalled。 - false：否
    └ updatedboolean消息是否被更新。
- true：是 - false：否
    └ chat_idstring消息所属的群 ID。你可以调用获取群信息接口，根据群 ID 获取群详情。
    └ sendersender当前消息的发送者信息。
      └ idstring发送者的 ID。
      └ id_typestring发送者的 ID 类型。
可能值有： - open_id：表示发送者为用户，且返回的 ID 是用户的 open_id。 - app_id：表示发送者为应用，且返回的 ID 是应用的 app_id。
      └ sender_typestring发送者类型。
可能值有： - user: 用户 - app: 应用 - anonymous: 匿名 - unknown: 未知
      └ tenant_keystring租户唯一标识。该标识用来识别租户，也可以用来获取租户访问凭证（tenant_access_token）。
    └ bodymessage_body通过 body 内的 content 参数，返回当前的消息内容。
      └ contentstring消息内容，JSON 结构序列化后的字符串，不同消息类型（msg_type）对应不同内容。
注意：卡片消息内容与在卡片搭建工具中获取的卡片 JSON 不一致，暂不支持返回原始卡片 JSON
    └ mentionsmention\[\]消息内被 @ 的用户或机器人列表。
      └ keystring被 @ 的用户或机器人序号。例如，第 3 个被 @ 到的成员，取值为 @_user_3。
      └ idstring被 @ 的用户或机器人的 open_id。
      └ id_typestring被 @ 的用户或机器人的 ID 类型，目前仅支持 open_id (了解什么是 Open ID)。
      └ namestring被 @ 的用户或机器人的姓名。
      └ tenant_keystring租户唯一标识。该标识用来识别被 @ 用户或机器人的租户，也可以用来获取租户访问凭证（tenant_access_token）。
    └ upper_message_idstring合并转发消息中，上一层级的消息 ID，仅在合并转发场景会有返回值。了解 upper_message_id 可参见消息管理概述。

响应体示例 ​

json
{
    "code": 0,
    "msg": "success",
    "data": {
        "has_more": true,
        "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状态码错误码描述排查建议
400230001Your request contains an invalid request parameter.参数错误，可根据接口实际返回的错误信息，并参考接口文档内容，检查输入参数是否填写错误。
400230002The bot can not be outside the group.机器人不在对应群组中。你需要将应用机器人添加到接收消息的群组中。如何添加机器人参考机器人使用指南。
400230006Bot ability is not activated.应用未启用机器人能力。启用方式参见如何启用机器人能力。
400230013Bot has NO availability to this user.目标用户（以用户的 user_id/open_id/union_id/email 指定的消息接收者）或单聊用户（以群聊的 chat_id 指定的消息接收者，但 chat_id 对应的群聊类型为单聊 p2p）不在应用机器人的可用范围内，或者是在应用的禁用范围内。 注意：如果目标用户已离职，也会报错 230013。 解决方案： 1. 登录开发者后台，找到并进入指定应用详情页。 2. 在左侧导航栏进入 应用发布 > 版本管理与发布 页面，点击 创建版本。 3. 在 版本详情 页面，找到 可用范围 区域，点击 编辑。 4. 在弹出的对话框内，配置应用的可用范围，将用户添加至可用范围内。 5. 在页面底部点击 保存，并发布应用使配置生效。 6. （可选）如果以上配置完成后仍报错，则需要联系企业管理员登录管理后台，在 工作台 > 应用管理 中进入指定应用详情页，在 应用可用范围 内查看该用户是否被设置为了 禁用成员。 具体操作参见配置应用可用范围。
400230027Lack of necessary permissions.无权进行本次操作。可能的原因有： 1. 缺少相应权限，可根据实际的错误信息进行排查。 2. 未检查到用户授权信息。 3. 如果需要机器人在外部群操作，则需要先为机器人开启对外共享能力，详情参见机器人支持外部群和外部用户单聊。
400230073The thread is invisible to the operator.该话题对于当前操作者不可见。如果群聊关闭了 新成员可查看历史消息 且此话题为当前操作者进入群聊之前创建的，则该话题需要操作者被动订阅才可见（如其他用户在话题中@操作者）。
400230110Action unavailable as the message has been deleted.消息已删除，无法执行操作。
400231203The chat type is not supported.群类型不支持获取消息，比如群设置中如果开启了保密模式禁止复制消息，则无法获取消息。
400231204The app type is not supported.开启了对外共享或关联组织的应用不支持以用户身份请求该接口

其他未列出的错误码请参见服务端通用错误码。

内容来源：飞书开放平台 · 自动爬取整理

本镜像仅供学习与查阅，文档版权归飞书所有