飛書訊息
飛書訊息能力用於把產品中的業務變化推送到飛書，也可以圍繞群訊息和事件訂閱搭建協作流程。常見場景包括告警通知、訂單狀態提醒、審批流通知、群訊息看板和互動卡片。
適合什麼場景
- 系統狀態變化後，自動向飛書群或成員發送通知。
- 使用機器人訊息卡片承載待處理事項、審批結果或業務摘要。
- 監聽指定群聊中的訊息或事件，並把它們同步到產品頁面。
- 將營運、客服、專案協作等群訊息沉澱為可檢索的記錄。
接入前需要準備
| 準備項 | 說明 |
|---|
| 飛書基礎插件 | 先啟用 飛書插件，並填寫 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 中啟用
啟用飛書基礎插件
先在「研發」→「技能庫」啟用飛書插件，完成飛書應用憑證配置。
確認訊息模式
決定是只發送機器人通知，還是還需要讀取群訊息、做訊息看板或接收事件。
開通飛書權限並發佈
按訊息模式申請對應權限。如果涉及事件訂閱，還需要配置事件訂閱地址。
啟用飛書訊息
在技能庫中點擊「飛書訊息」，告訴 superun 你要接入的訊息場景，例如「訂單支付成功後發到營運群」。
補充發送目標和內容規則
說明訊息要發給哪個群或成員、什麼事件觸發、訊息裡需要展示哪些欄位。
完成飛書後台權限和測試
在飛書開放平台補充權限並發佈版本，然後回到產品中測試訊息發送或事件接收。
常見限制
- 機器人必須在目標群中，才能向該群發送訊息或接收相關群事件。
- 新增權限後未發佈應用版本，會導致權限不足。
- 群訊息監聽通常需要配置事件訂閱，不能只開通發送訊息權限。
- 群列表為空時，常見原因不是權限，而是機器人還沒有加入任何群。
