> ## Documentation Index
> Fetch the complete documentation index at: https://docs.superun.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 飞书消息

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

# 飞书消息

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

***

## 适合什么场景

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

***

## 接入前需要准备

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

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

***

## 飞书后台需要开通的权限

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

### 只做机器人主动发消息

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

批量导入示例：

```json theme={null}
{
  "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        | 通过事件订阅接收群内新消息         |

批量导入示例：

```json theme={null}
{
  "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"]
  }
}
```

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

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

***

## 如何在 superun 中启用

<Steps>
  <Step title="启用飞书基础插件">
    先在「研发」→「技能库」启用飞书插件，完成飞书应用凭证配置。
  </Step>

  <Step title="确认消息模式">
    决定是只发送机器人通知，还是还需要读取群消息、做消息看板或接收事件。
  </Step>

  <Step title="开通飞书权限并发布">
    按消息模式申请对应权限。如果涉及事件订阅，还需要配置事件订阅地址。
  </Step>

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

  <Step title="补充发送目标和内容规则">
    说明消息要发给哪个群或成员、什么事件触发、消息里需要展示哪些字段。
  </Step>

  <Step title="完成飞书后台权限和测试">
    在飞书开放平台补充权限并发布版本，然后回到产品中测试消息发送或事件接收。
  </Step>
</Steps>

***

## 常见限制

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