> ## 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 中接入飛書機器人訊息、群通知、訊息卡片和事件訂閱。

# 飛書訊息

飛書訊息能力用於把產品中的業務變化推送到飛書，也可以圍繞群訊息和事件訂閱搭建協作流程。常見場景包括告警通知、訂單狀態提醒、審批流通知、群訊息看板和互動卡片。

***

## 適合什麼場景

* 系統狀態變化後，自動向飛書群或成員發送通知。
* 使用機器人訊息卡片承載待處理事項、審批結果或業務摘要。
* 監聽指定群聊中的訊息或事件，並把它們同步到產品頁面。
* 將營運、客服、專案協作等群訊息沉澱為可檢索的記錄。

***

## 接入前需要準備

| 準備項    | 說明                                                                       |
| ------ | ------------------------------------------------------------------------ |
| 飛書基礎插件 | 先啟用 [飛書插件](/zh-Hant/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>

***

## 常見限制

* 機器人必須在目標群中，才能向該群發送訊息或接收相關群事件。
* 新增權限後未發佈應用版本，會導致權限不足。
* 群訊息監聽通常需要配置事件訂閱，不能只開通發送訊息權限。
* 群列表為空時，常見原因不是權限，而是機器人還沒有加入任何群。