移除 Pin 消息
移除一条指定消息的 Pin。
前提条件
- 应用需要开启机器人能力。
- 移除 Pin 消息时，机器人必须在消息所属的会话内。
使用限制
- 当前操作者不可见的消息无法移除 Pin。
- 对同一条消息移除 Pin 的操作不能超过 5 QPS。
注意事项
如果消息未被 Pin 或已被撤回，则该接口返回成功信息 "msg": "success"。
请求
| 项目 | 值 |
|---|---|
| HTTP URL | https://open.feishu.cn/open-apis/im/v1/pins/:message_id |
| HTTP Method | DELETE |
| 接口频率限制 | 1000 次/分钟、50 次/秒 |
| 支持的应用类型 | custom,isv |
| 权限要求 调用该 API 所需的权限。开启其中任意一项权限即可调用 开启任一权限即可 | im:message 获取与发送单聊、群组消息 im:message.pins:write_only 添加、 取消 Pin 消息 im:message:send_as_bot 以应用的身份发消息 |
请求头
| 名称 | 类型 | 必填 | 描述 |
|---|---|---|---|
| Authorization | string | 是 | tenant_access_token 或 user_access_token 值格式："Bearer access_token" 示例值："Bearer u-7f1bcd13fc57d46bac21793a18e560" 了解更多：如何选择与获取 access token |
路径参数
| 名称 | 类型 | 描述 |
|---|---|---|
message_id | string | 待移除 Pin 的消息 ID。ID 获取方式： - 调用发送消息接口后，从响应结果的 message_id 参数获取。 - 监听接收消息事件，当触发该事件后可以从事件体内获取消息的 message_id。 - 调用获取会话历史消息接口，从响应结果的 message_id 参数获取。示例值："om_dc13264520392913993dd051dba21dcf" |
响应
响应体
| 名称 | 类型 | 描述 |
|---|---|---|
code | int | 错误码，非 0 表示失败 |
msg | string | 错误描述 |
data | \- | - |
响应体示例
json
{
"code": 0,
"msg": "success",
"data": {}
}错误码
| 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 | 230045 | The chat not exist. | 消息所属的群聊不存在，请检查群聊是否已解散。 |
| 400 | 230046 | No Permission to Pin/Unpin messages in the chat. | 该群设置仅群主和群管理员可以 Pin 消息，请检查操作者在群内的身份。 |
| 400 | 230047 | Pin/Unpin message trigger message_id limit. | 对同一条消息 Pin/Unpin 触发限流策略，请降低请求速度，稍后再试。 |
| 400 | 230050 | The message is invisible to the operator. | 该消息对于操作者不可见，无法进行本操作。 |
| 400 | 232009 | Your request specifies a chat which has already been dissolved. | 相关群组已被解散，无法进行当前操作。 |
其他服务端错误码参考：服务端错误码说明。