跳轉到主要內容

​
飛書插件

飛書插件是 superun 連接飛書開放平台的基礎能力。啟用後，你可以把飛書帳號、組織架構、群訊息、機器人通知、日程和任務接入到自己的產品中。 飛書能力採用「基礎插件 + 子能力」的方式組織：基礎插件負責保存飛書應用憑證和登入授權，子能力按業務場景逐個啟用。你不需要一次接入所有能力。

​
可以接入哪些能力

能力適合場景說明
飛書登入內部系統、客戶門戶、企業白名單訪問用戶用飛書帳號登入你的產品，是多數飛書能力的基礎
飛書訊息群通知、機器人訊息、事件訂閱把業務提醒、狀態變化、告警推送到飛書
飛書日程會議安排、日程同步、可用時間查詢在產品中建立、查詢或同步飛書日曆事件
飛書任務待辦建立、任務分配、狀態同步將產品裡的工作事項同步為飛書任務
飛書通訊錄成員選擇、部門樹、組織權限讀取企業成員與部門資訊，用於組織架構相關流程

​
接入前需要準備

  • 飛書開放平台管理員權限。
  • 一個企業自建應用，並取得 App ID 和 App Secret。
  • 已發佈的 superun 專案網域，用於配置飛書回呼地址和安全網域。
  • 根據要接入的子能力，在飛書後台開通對應權限，並建立新版本發佈。
如果只接入飛書登入，通常只需要完成基礎應用和登入權限配置。任務、日程等子能力會在需要時追加授權。

​
子能力權限速查

子能力需要額外開通的權限 key類型說明
飛書登入contact:user.base:readonlyuser讀取登入用戶基礎身份資訊
飛書任務task:task:read、task:task:writeuser查詢和讀寫飛書任務
飛書日程calendar:calendar:readonly、calendar:calendaruser讀取和寫入飛書日曆與日程
飛書訊息im:message:send_as_bot、im:chat:readonlytenant機器人發訊息、獲取機器人所在群
飛書訊息看板im:message:readonly、im:message.group_msg、im:message.receive_v1tenant / user讀取群歷史訊息、接收新訊息事件
飛書通訊錄contact:contact.base:readonly、contact:department.base:readonly、contact:user.base:readonlytenant讀取通訊錄、部門和成員基礎資訊
飛書通訊錄可選欄位contact:user.email:readonly、contact:user.phone:readonlytenant讀取成員電子郵件和手機號
在飛書開放平台申請權限後，必須建立並發佈新版本。任務、日程等 user 類型權限還需要用戶重新同意授權。

​
建議接入順序

1

先啟用飛書基礎插件

在專案的「研發」→「技能庫」中啟用飛書插件，按提示填寫飛書應用的 App ID 和 App Secret。
2

先跑通飛書登入

飛書登入會建立用戶身份和授權基礎。後續任務、日程等用戶級能力會複用這套登入授權。
3

按場景啟用子能力

根據業務需要繼續啟用飛書訊息、日程、任務或通訊錄，不需要重複配置基礎憑證。
4

完成平台授權和測試

如果新開通了權限，需要在飛書開放平台發佈新版本；涉及用戶授權的能力，需要用戶重新同意授權。

​
常見問題

通常不需要。任務、日程、訊息和通訊錄會複用飛書基礎插件裡的應用憑證。你只需要按對應能力補充飛書後台權限，並在需要時讓用戶重新授權。
飛書權限變更後需要建立新版本並發佈。對於任務、日程這類用戶級能力，用戶還需要重新同意授權，新的權限才會生效。
可以。先啟用飛書基礎插件，再按業務需要啟用某個子能力即可。

​
子能力說明

飛書訊息

接入機器人通知、群訊息、訊息卡片和事件訂閱。

飛書日程

接入日程建立、查詢、會議安排和可用時間檢查。

飛書任務

接入任務建立、負責人、狀態同步和提醒流程。

飛書通訊錄

接入成員查詢、部門樹、組織架構和身份映射。