获取群内 Pin 消息

获取指定群、指定时间范围内的所有 Pin 消息。

前提条件

• 应用需要开启机器人能力。
• 获取 Pin 消息时，机器人必须在消息所属的会话内。

注意事项

• 获取的 Pin 消息按 Pin 的创建时间降序排列。
• 接口默认限流为 50 QPS。

请求

项目	值
HTTP URL	https://open.feishu.cn/open-apis/im/v1/pins
HTTP Method	GET
接口频率限制	1000 次/分钟、50 次/秒
支持的应用类型	custom,isv
权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可	im:message 获取与发送单聊、群组消息 im:message.pins:read 查看 Pin 消息 im:message:readonly 获取单聊、群组消息

请求头

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

查询参数

名称	类型	必填	描述
chat_id	string	是	待获取 Pin 消息的群组 ID。获取方式参见群 ID 说明。 示例值：oc_234jsi43d3ssi993d43545f
start_time	string	否	获取 Pin 消息的起始时间，毫秒级时间戳。 注意： - 若未传值默认获取到群聊内最早的 Pin 消息。 - 传值时需小于 end_time 值。 示例值：1658632251800
end_time	string	否	获取 Pin 消息的结束时间，毫秒级时间戳。 注意： - 若未传值默认从群聊内最新的 Pin 消息开始获取。 - 传值时需大于 start_time 值。 示例值：1658731646425
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	\-	-
└ items	pin\[\]	Pin 的操作信息
└ message_id	string	Pin 的消息 ID
└ chat_id	string	Pin 消息所在的群聊 ID
└ operator_id	string	Pin 的操作人 ID
└ operator_id_type	string	Pin 的操作人 ID 类型。可能值有： - open_id：表示操作人为用户，此时 operator_id 返回值为用户的 open_id。 - app_id：表示操作人为应用，此时 operator_id 返回值为应用的 app_id。
└ create_time	string	Pin 的创建时间（毫秒级时间戳）
└ has_more	boolean	是否还有更多项
└ page_token	string	分页标记，当 has_more 为 true 时，会同时返回新的 page_token，否则不返回 page_token

响应体示例

{
    "code": 0,
    "msg": "success",
    "data": {
        "items": [
            {
                "message_id": "om_dc13264520392913993dd051dba2123",
                "chat_id": "oc_a0553eda9014c201e6969b478895123",
                "operator_id": "ou_7d8a6e6df7621556ce0d21922b6767123",
                "operator_id_type": "open_id",
                "create_time": "1615380573211"
            }
        ],
        "has_more": true,
        "page_token": "GxmvlNRvP0NdQZpa7yIqf_Lv_QuBwTQ8tXkX7w-irAghVD_TvuYd1aoJ1LQph86O-XImC4X9j9FhU123=="
    }
}

错误码

HTTP状态码	错误码	描述	排查建议
400	230001	Your request contains an invalid request parameter.	参数错误，请根据接口返回的错误信息并参考文档检查输入参数。
400	230002	The bot can not be outside the group.	机器人不在对应群组中。你需要确保应用机器人已添加到待操作的群组中。如何添加机器人参考机器人使用指南。
400	230006	Bot ability is not activated.	应用未启用机器人能力。启用方式参见如何启用机器人能力。
400	230013	Bot 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. （可选）如果以上配置完成后仍报错，则需要联系企业管理员登录管理后台，在 工作台 > 应用管理 中进入指定应用详情页，在 应用可用范围 内查看该用户是否被设置为了 禁用成员。 具体操作参见配置应用可用范围。
400	230027	Lack of necessary permissions.	无权进行本次操作。可能的原因有： 1. 缺少相应权限，可根据实际的错误信息进行排查。 2. 未检查到用户授权信息。 3. 如果需要机器人在外部群操作，则需要先为机器人开启对外共享能力，详情参见机器人支持外部群和外部用户单聊。
400	230048	Get chat pins trigger app_id limit.	获取 Pin 消息触发频率限制。请降低请求速度，稍后再试。

其他服务端错误码参考：服务端错误码说明。