接入飛書機器人

Buda 原生支援透過 WebSocket 長連線接入飛書機器人，無需設定公網 Webhook URL 或內網穿透，只需提供 App ID 和 App Secret 即可建立即時 AI 對話。

步驟 1：建立飛書應用程式

1.1 進入飛書開發者平台

前往 飛書開放平台 並登入。

Lark（國際版）租戶請前往 https://open.larksuite.com/app，並在設定中設置 domain: "lark"。

1.2 建立企業自建應用程式

1. 點擊 建立企業自建應用程式
2. 填寫應用程式名稱、描述和圖示
3. 點擊 建立

1.3 記錄憑證

在左側選單 憑證與基礎資訊 中記錄：

App ID：      cli_xxxxxxxxxxxx
App Secret：  xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

App Secret 預設隱藏，點擊「查看」顯示。請妥善保管。

1.4 設定權限

在 權限管理 → 權限設定 中，點擊 批次匯入權限，貼上以下內容：

{
  "scopes": {
    "tenant": [
      "aily:file:read",
      "aily:file:write",
      "application:application.app_message_stats.overview:readonly",
      "application:application:self_manage",
      "application:bot.menu:write",
      "cardkit:card:read",
      "cardkit:card:write",
      "contact:user.employee_id:readonly",
      "corehr:file:download",
      "event:ip_list",
      "im:chat.access_event.bot_p2p_chat:read",
      "im:chat.members:bot_access",
      "im:message",
      "im:message.group_at_msg:readonly",
      "im:message.p2p_msg:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource"
    ],
    "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"]
  }
}

1.5 首次發布應用程式

必須先發布，才能啟用事件訂閱。

1. 左側選單 → 版本管理與發布 → 建立版本
2. 版本號填 1.0.0，點擊 儲存 → 申請上線
3. 等待審核通過（企業自建應用程式通常自動通過）

步驟 2：在 Buda 中設定頻道

開啟 Buda 的 Channel 介面，選擇飛書，填入 App ID 和 App Secret 後儲存。

Buda 會立即在背景透過 WebSocket 與飛書伺服器建立長連線。

⚠️ 必須先完成此步驟，飛書才能偵測到長連線，否則下一步的事件設定無法儲存。

步驟 3：啟用事件訂閱

1. 左側選單 → 事件和回調 → 事件設定
2. 開啟 使用長連線接收事件 開關
3. 點擊 新增事件，新增 im.message.receive_v1
4. 點擊 儲存

⚠️ 如果無法啟用長連線，表示應用程式尚未發布，請先完成步驟 1.5。

步驟 4：發布新版本

新增事件後，必須發布新版本才能生效：

1. 版本管理與發布 → 建立版本，版本號自增（如 1.0.1）
2. 點擊 儲存 → 申請上線

步驟 5：測試

1. 開啟飛書客戶端，搜尋你的機器人名稱
2. 傳送一條訊息，例如：你好
3. Buda 回覆後，即可正常對話 🎉

常見問題

機器人不回應

長連線無法啟用

應用程式未發布。完成步驟 1.5 並等待 1-2 分鐘後重試。

App Secret 外洩

1. 在飛書開放平台重置 App Secret
2. 更新 Buda 設定中的 App Secret

支援的訊息類型

接收

• ✅ 文字、富文字
• ✅ 圖片、檔案、音訊、影片
• ✅ 表情包

傳送

• ✅ 文字、圖片、檔案、音訊、影片
• ✅ 互動式卡片（串流輸出）

設定參考