飛書接入指南

將飛書機器人連線到 Elisi Agent

完成連線後，你可以直接在飛書中私聊自己的企業機器人，讓 Elisi Agent 幫你記錄和查詢 任務、清單等內容。

開始前

你需要：

• 一個 Elisi 賬號。
• 飛書企業自建應用的建立和釋出許可權。
• 企業管理員批准應用許可權（如果企業要求審批）。

1. 建立飛書應用

1. 開啟飛書開放平臺，進入開發者後臺。
2. 建立一個“企業自建應用”。
3. 在“新增應用能力”中啟用“機器人”。
4. 在“許可權管理”中新增：
   • 獲取使用者發給機器人的單聊訊息。
   • 以應用身份傳送訊息。
   • 如需在群聊中使用，再新增接收群聊中機器人被 @ 訊息的許可權。

記下應用的 App ID 和 App Secret。

2. 在 Elisi 中連線機器人

1. 開啟 Elisi 的“設定”。
2. 在“Elisi AI”區域選擇“飛書 / Lark 機器人”。
3. 平臺選擇“飛書”。使用國際版 Lark 時選擇“Lark”。
4. 填寫機器人名稱（可選）、App ID、App Secret 和飛書後臺顯示的 Verification Token。
5. 點選“連線機器人”。

Elisi 驗證成功後會顯示：

• 事件回撥 URL。
• 一次性繫結命令。

App Secret 不會再次顯示。Elisi 會加密儲存它，不會將其傳送給 Agent。

3. 配置事件回撥

回到飛書開放平臺：

1. 開啟“事件與回撥”或“事件訂閱”。

2. 選擇“將事件傳送至開發者伺服器”。

3. 複製 Elisi 顯示的“事件回撥 URL”，貼上為請求地址。

4. Encrypt Key 必須留空。

5. 儲存 URL，等待飛書提示校驗成功。

6. 點選“新增事件”，新增：

   接收消息（im.message.receive_v1）
   

僅通過 URL 校驗還不夠，必須另外新增 im.message.receive_v1。

4. 釋出並安裝應用

1. 在飛書開放平臺建立新版本。
2. 確認新版本包含剛新增的許可權和訊息事件。
3. 提交稽核併發布；需要管理員審批時，先完成審批。
4. 將應用安裝到企業，並確保你的飛書賬號位於應用可用範圍內。

每次修改許可權或事件訂閱後，都需要重新發布版本，否則修改不會生效。

5. 繫結 Elisi 賬號

配置和釋出通常會超過 15 分鐘。釋出完成後，建議先回到 Elisi：

1. 在機器人卡片中點選“生成新繫結碼”。

2. 複製完整的一次性命令，例如：

   /elisi-bind AbCdEf123
   

3. 在 15 分鐘內開啟與機器人的一對一私聊併發送該命令。

4. 看到繫結成功提示後，回到 Elisi 重新整理狀態。

狀態從“等待繫結”變為“已連線”即表示配置完成。首次繫結不能在群聊中進行。

6. 開始使用

• 私聊：直接向機器人傳送文本。
• 群聊：必須由已繫結的使用者 @ 機器人後傳送訊息。
• 解除連線：在 Elisi 的機器人卡片中點選“解除連線”。

當前版本支援文本訊息，不支援 Encrypt Key 加密回撥、附件、互動卡片或多人共享同一個 Elisi 賬號。

常見問題

問題	處理方法
回撥 URL 校驗失敗，未返回 challenge	確認 URL 完整、Verification Token 一致，並將 Encrypt Key 清空後重新儲存。
URL 校驗成功，但私聊機器人沒有反應	確認已新增 im.message.receive_v1，並在新增事件和許可權後重新發布、審批和安裝最新版本。
Elisi 一直顯示“等待繫結”	點選“生成新繫結碼”，在 15 分鐘內通過一對一私聊傳送完整命令。舊繫結碼會失效。
繫結成功但機器人不回覆	檢查是否已批准“以應用身份傳送訊息”許可權，並確認該許可權已包含在最新發布版本中。
群聊中機器人不響應	先通過私聊完成繫結，再由已繫結使用者在群聊中 @ 機器人。
找不到機器人或無法私聊	檢查應用是否已安裝，以及當前賬號是否在應用可用範圍內。

仍無法使用時，可先在飛書開放平臺的“事件推送記錄”中確認是否產生了 im.message.receive_v1。沒有推送記錄通常表示事件、許可權、釋出版本或應用可用範圍尚未生效。