接入本身不難，難的是「收不到訊息」時不知道卡在哪一步
把「飛書 AI 機器人」拆開看，它其實就是三件事的組合：一個應用身分（誰在說話）、一條收訊息的通道（使用者的話怎麼到你這裡）、一條發訊息的通道（你的回答怎麼回到對話裡）。
| 段 | 做什麼 | 失敗時的典型症狀 |
|---|---|---|
| 身分 | 建立自建應用，拿到 App ID 與 App Secret | 呼叫介面一律回傳鑑權失敗 |
| 收訊息 | 事件訂閱回呼 或 長連線 | 後台日誌一條請求都沒有 |
| 發訊息 | 呼叫發訊息介面，把回答寫回會話 | 收到請求，但群裡沒反應 |
這三段是串聯關係：前一段不通，後一段永遠看不到現象。所以排錯的第一原則是按段驗證，而不是一上來就懷疑模型或程式碼。
在飛書開放平台後台建立企業自建應用，建立後會得到兩個關鍵值：App ID 和 App Secret。這兩個值的作用是換取存取憑證（tenant access token），後續所有介面呼叫都靠它鑑權。
這一步的驗證方法很簡單：先用憑證換一次 token，能拿到就說明身分段通了。
# 換取存取憑證（示意，欄位以官方文件為準）
POST /open-apis/auth/v3/tenant_access_token/internal
{
"app_id": "cli_xxx",
"app_secret": "xxx"
}
# 成功回傳 access_token 與 expire（秒）要點：token 有有效期，不要每次請求都重新換，也不要把 token 寫死在程式碼裡長期使用。正確做法是快取 + 提前刷新（例如剩餘有效期不足 5 分鐘就重換一次）。
飛書的權限是按能力逐項申請的，不是「開了機器人就全通」。AI 機器人場景通常涉及三類權限：
| 權限類別 | 用途 | 漏了會怎樣 |
|---|---|---|
| 訊息與群組 | 接收訊息事件、發送訊息、讀取群資訊 | 能收到事件但發不出去，或乾脆收不到 |
| 通訊錄（按需） | 把使用者身分對應到內部帳號 | 無法判斷「誰在問」，權限分層做不了 |
| 雲端文件 / 知識庫（按需） | 讓機器人讀企業文件回答問題 | 知識問答答不出，或答非所問 |
要點：權限申請後通常需要發佈版本並等待管理員審核才會生效。很多人改完權限立刻測試，發現還是不通，其實是版本沒發佈。這一步的驗證方法是：在後台的權限頁確認狀態是「已生效」，而不是「已申請」。
這是整篇最關鍵的一個選擇。飛書支援兩種把訊息送到你服務端的方式，它們的適用場景完全不同：
| 維度 | 事件訂閱回呼（Webhook） | 長連線 |
|---|---|---|
| 原理 | 飛書主動 POST 到你的公網位址 | 你的服務主動連到飛書，保持長連線 |
| 需要公網位址 | 需要，且必須 HTTPS | 不需要 |
| 需要處理驗簽 | 需要 | 不需要（連線本身即鑑權） |
| 適合場景 | 已有公網服務的團隊 | 內網部署、本機開發、私有化環境 |
| 主要風險 | 位址不可達、憑證問題、驗簽失敗 | 連線中斷後需自動重連 |
判據很直接：你的服務有沒有一個可被公網存取的 HTTPS 位址？有就優先回呼（更標準、更易排查）；沒有（內網、私有化、本機除錯）就用長連線。
如果企業整體走私有化部署路線，長連線通常是更省事的選擇，資料邊界也更容易講清楚——私有化部署的整體考量見《AI 私有化部署方案怎麼選》。
選了回呼方式，服務端要處理的不只是「收到訊息」，還有三件容易被忽略的事：
設定回呼位址時，飛書會先發一個校驗請求，你需要把其中的 challenge 值原樣回傳，位址才會被標記為驗證通過。這一步不通，後面所有事件都不會推過來。
校驗通過後，正式事件會帶簽章標頭。服務端必須用應用憑證按官方演算法重算簽章並比對，不一致直接拒絕。不做驗簽等於把你的機器人介面暴露給任何人，這是安全底線，不是可選項。
回呼介面要儘快回傳成功，業務處理（尤其是呼叫大型模型）放到非同步佇列裡做。同步等模型生成完再回傳，很容易逾時，飛書會重推事件，導致同一條訊息被處理多次。
冪等性是這裡最容易漏的一條：事件可能重複投遞，處理邏輯必須按事件 ID 去重，否則使用者會看到機器人重複回答同一句話。
權限和通道都通了，還有一件事：機器人必須在會話裡。群聊場景下，機器人需要被拉進群；預設情況下它只在被 @ 時才收到訊息，這是產品設計而非程式錯誤。
| 場景 | 觸發條件 | 注意點 |
|---|---|---|
| 群聊 | 被 @ 提及 | 訊息內容裡通常帶 @ 佔位符，取問題時要去掉 |
| 單聊 | 直接發訊息給機器人 | 需要開放單聊能力並發佈版本 |
| 話題群 | 在被 @ 的話題內 | 回覆要落在同一話題，否則會跑到主群 |
多平台並存的團隊還要注意一件事：不同 IM 的訊息結構、@ 語法、富文字格式都不一樣。把「取使用者問題」這段邏輯做成平台無關的中間層，後面接企業微信、釘釘時就不用重寫業務邏輯——橫向差異見《釘釘、飛書、企業微信 AI 機器人怎麼選》。
AI 回答通常需要幾秒到幾十秒。如果等全部生成完再一次性發出去，使用者會覺得「機器人卡住了」。串流回覆的做法是：先發一條佔位訊息，再按增量更新這條訊息的內容。
# 思路示意（介面與欄位以官方文件為準）
1. 收到事件 → 立即回傳成功
2. 發送一條佔位訊息，拿到 message_id
3. 模型串流輸出 → 按節流間隔（如 300-500ms）更新該訊息
4. 生成結束 → 做最後一次完整更新要點：更新頻率不要太高，飛書介面有頻率限制，逐 token 更新會被限流；也不要太低，否則和一次性發送沒區別。實務上 300–500ms 一次是比較穩的區間，並且要處理「更新失敗時降級為一次性發送」。
接入完成不等於可以上線。下面這張表建議逐項打勾，任何一項沒驗過都不要宣布「接好了」。
| # | 驗收項 | 判據 |
|---|---|---|
| 1 | 憑證可換取 token | 獨立腳本呼叫成功，不依賴業務程式碼 |
| 2 | 權限已生效 | 後台狀態為「已生效」，不是「已申請」 |
| 3 | 收訊息通道通 | 服務端日誌能看到真實事件，不是只有校驗請求 |
| 4 | 驗簽已開啟 | 偽造請求被拒絕，有明確日誌 |
| 5 | 冪等已實作 | 同一事件重複投遞只處理一次 |
| 6 | 群聊 / 單聊都測過 | 兩種入口都能正常回答 |
| 7 | 串流回覆正常 | 首字延遲可感知地短於完整生成時間 |
| 8 | 異常降級處理 | 模型逾時 / 限流時有使用者可讀的提示，不是靜默 |
先查回呼位址是否通過位址校驗，再查事件是否真的訂閱了（訂閱了權限但沒訂閱事件，同樣不會推）。
多半是權限未生效或版本未發佈。確認後台權限狀態，並重新發佈一次版本。
檢查是否用了原始請求內容參與簽章（很多框架會自動解析 JSON，導致簽章對不上）。要拿未解析的原始內容計算。
通常是缺發訊息權限，或用了錯誤的會話標識。確認訊息是發到 chat_id 還是 open_id，兩者不能混用。
確認機器人已被拉進群、且事件訂閱包含群訊息事件。私聊正常但群裡沒反應，基本就是這一條。
回呼逾時導致飛書重推。把業務處理改成非同步，並按事件 ID 做冪等去重。
降低更新頻率到 300–500ms 一次，並在限流時降級為一次性發送，而不是直接報錯。
先確認部署環境能否存取外網（換 token 需要）。內網環境直接改用長連線，別在出網策略上死磕。
飛書 AI 機器人的接入，難點不在寫程式，而在把四段鏈路拆開、每段單獨可驗證。身分、權限、收訊息、發訊息，任何一段黑了，現象都是「沒反應」——沒有分段驗證，就只能靠猜。
把本文的 7 步當作施工順序，把 8 條排錯清單當作卡住時的檢索表，把驗收表當作上線關卡。這套順序走完，接入本身大概半天到一天，剩下的時間應該花在「回答品質」和「權限邊界」上，那才是真正決定這個機器人有沒有人用的部分。