飞书消息

在 superun 中接入飞书机器人消息、群通知、消息卡片和事件订阅。

飞书消息

飞书消息能力用于把产品中的业务变化推送到飞书，也可以围绕群消息和事件订阅搭建协作流程。常见场景包括告警通知、订单状态提醒、审批流通知、群消息看板和交互卡片。

---

适合什么场景

• 系统状态变化后，自动向飞书群或成员发送通知。
• 使用机器人消息卡片承载待处理事项、审批结果或业务摘要。
• 监听指定群聊中的消息或事件，并把它们同步到产品页面。
• 将运营、客服、项目协作等群消息沉淀为可检索的记录。

---

接入前需要准备

准备项	说明
飞书基础插件	先启用 飞书插件，并填写 App ID 和 App Secret
机器人能力	在飞书开放平台启用机器人能力，并把机器人添加到目标群
消息权限	按实际场景开通发送消息、读取群列表、读取消息或事件订阅权限
版本发布	权限变更后，需要创建新版本并发布

如果只是向某个群快速发送通知，也可以使用群自定义机器人 Webhook。需要更灵活的目标选择、群列表读取或事件订阅时，建议使用飞书应用机器人能力。

---

飞书后台需要开通的权限

飞书消息有两种常见接入方式，所需权限不同。

只做机器人主动发消息

权限 key	权限名称	类型	用途
im:message:send_as_bot	以应用身份发送消息	tenant	通过应用机器人向群或成员发送消息
im:chat:readonly	获取机器人所在群列表	tenant	让产品可以列出机器人已加入的群，供用户选择发送目标

批量导入示例：

{
  "scopes": {
    "tenant": ["im:message:send_as_bot", "im:chat:readonly"],
    "user": []
  }
}

需要读取群消息或做消息看板

在上面两条基础上，继续按需开通：

权限 key	权限名称	类型	用途
im:message:readonly	读取历史消息	tenant / user	拉取群历史消息或读取消息内容
im:message.group_msg	读取群聊消息	tenant / user	读取群聊消息，部分历史消息接口会要求该权限
im:message.receive_v1	接收新消息事件	tenant	通过事件订阅接收群内新消息

批量导入示例：

{
  "scopes": {
    "tenant": [
      "im:message:send_as_bot",
      "im:chat:readonly",
      "im:message:readonly",
      "im:message.group_msg",
      "im:message.receive_v1"
    ],
    "user": ["im:message:readonly", "im:message.group_msg"]
  }
}

如果只是把通知推到固定群，也可以使用飞书群自定义机器人 Webhook，这种方式不需要在开放平台申请 API 权限，但只能发到固定群，不适合做群列表选择和消息看板。

开通权限后需要发布飞书应用新版本。需要接收新消息时，还要在飞书开放平台配置事件订阅地址，并确保机器人已经加入目标群。

---

如何在 superun 中启用

1. 启用飞书基础插件

   先在「研发」→「技能库」启用飞书插件，完成飞书应用凭证配置。

2. 确认消息模式

   决定是只发送机器人通知，还是还需要读取群消息、做消息看板或接收事件。

3. 开通飞书权限并发布

   按消息模式申请对应权限。如果涉及事件订阅，还需要配置事件订阅地址。

4. 启用飞书消息

   在技能库中点击「飞书消息」，告诉 superun 你要接入的消息场景，例如“订单支付成功后发到运营群”。

5. 补充发送目标和内容规则

   说明消息要发给哪个群或成员、什么事件触发、消息里需要展示哪些字段。

6. 完成飞书后台权限和测试

   在飞书开放平台补充权限并发布版本，然后回到产品中测试消息发送或事件接收。

---

常见限制

• 机器人必须在目标群中，才能向该群发送消息或接收相关群事件。
• 新增权限后未发布应用版本，会导致权限不足。
• 群消息监听通常需要配置事件订阅，不能只开通发送消息权限。
• 群列表为空时，常见原因不是权限，而是机器人还没有加入任何群。