docs(lark): explain event subscriptions and app publishing

2026-10-28 11:25:35 +08:00 · 2026-10-09 21:00:27 +08:00
parent e6d92319a6
commit 0be4598c8a
3 changed files with 81 additions and 3 deletions
@@ -41,12 +41,38 @@ If you choose an existing app, a list of your apps will be shown:

 ![Config Success](/images/zh/deploy/bots/lark/lark_config_success.png)

-7. **Manually fill in the bot name** — it must match the Feishu bot name, otherwise the bot won't receive messages in groups
+7. The new adapter identifies the bot automatically; no bot name is needed to recognize group mentions. If the legacy adapter still shows this field, enter the same name as the Feishu bot.

 ![Fill Bot Name](/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

 8. Click **Submit** to complete

+### Additional permissions and event subscriptions
+
+<Note>
+An app created or authorized by QR code may not have all the permissions and event subscriptions your use case requires. Sending and receiving messages does not mean member join/leave events are subscribed. You can update the existing app in the developer console without creating another bot.
+</Note>
+
+1. Open the [Feishu developer console](https://open.feishu.cn/app) or [Lark developer console](https://open.larksuite.com/app). Select the app you created or authorized, using its App ID to confirm.
+2. Under **Permissions**, add the permissions required for your features. Permissions control which data and operations the bot can access.
+3. Under **Events & Callbacks > Event Configuration**, subscribe to the events you need. Subscriptions control which notifications are sent to LangBot; granting permissions does not automatically subscribe to events.
+4. Save the changes and complete any release or administrator approval requested by the platform. Once effective, trigger a new event to verify delivery; earlier actions are not replayed by adding a subscription.
+
+<Warning>
+**Remember to publish a new app version after adding events.** Complete the release under **Version Management & Release**, and wait for administrator approval if required. Adding and saving an event does not activate changes that are still pending release. LangBot may show a healthy connection while these events are not delivered.
+</Warning>
+
+If member join/leave events still do not arrive after subscribing, first check for changes pending release or approval. Once the new version is effective, have a member join or leave a group containing the bot again, then check the event records in LangBot.
+
+To receive group membership changes, the bot must be in the group and the app must subscribe to:
+
+| Feature | Feishu event |
+| --- | --- |
+| User joins a group | `im.chat.member.user.added_v1` |
+| User leaves or is removed from a group | `im.chat.member.user.deleted_v1` |
+
+The bot joining a group (`im.chat.member.bot.added_v1`) is a separate event and does not cover other members. Also configure **Event Routing** in LangBot to send these events to an Agent or plugin processor; pipelines only process message events.
+
 ---

 ## Create Bot
@@ -41,12 +41,38 @@ LangBot は Feishu アプリのワンクリック作成とクレデンシャル

 ![設定成功](/images/zh/deploy/bots/lark/lark_config_success.png)

-7. **ボット名を手動で入力** — 飛書のボット名と一致させる必要があります。一致しない場合、グループ内でメッセージを受信できません
+7. 新しいアダプターはボットを自動識別するため、グループ内のメンション認識用のボット名は不要です。旧版アダプターでこの項目が表示される場合は、飛書のボット名と一致させてください。

 ![ボット名の入力](/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

 8. **送信** をクリックして完了

+### 権限とイベント購読の追加
+
+<Note>
+QR コードで作成・認証したアプリには、必要な権限やイベント購読がすべて設定されているとは限りません。メッセージを送受信できても、メンバーの参加・退出イベントは未購読の場合があります。ボットを作り直す必要はなく、開発者コンソールで既存のアプリに設定を追加できます。
+</Note>
+
+1. [Feishu 開発者コンソール](https://open.feishu.cn/app)または [Lark 開発者コンソール](https://open.larksuite.com/app)で、作成・認証したアプリを選択します。App ID で確認できます。
+2. **権限管理**で必要な権限を追加します。権限は、ボットが利用できるデータや操作を決めます。
+3. **イベントとコールバック > イベント設定**で必要なイベントを購読します。購読は LangBot に送信される通知を決める設定です。権限を追加するだけではイベントは購読されません。
+4. 設定を保存し、プラットフォームから求められるバージョン公開や管理者承認を完了します。有効になった後で再度イベントを発生させて確認してください。購読前の操作は自動再送されません。
+
+<Warning>
+**イベントを追加した後は、アプリの新しいバージョンを公開してください。** 開発者コンソールの**バージョン管理と公開**で公開を完了し、管理者承認が必要な場合は承認を待ちます。イベントを追加・保存しただけでは、公開待ちの変更は有効になりません。LangBot が正常に接続されていても、これらのイベントが届かない場合があります。
+</Warning>
+
+購読後もメンバーの参加・退出イベントが届かない場合は、まず公開待ち・承認待ちの変更がないか確認してください。新しいバージョンが有効になった後、ボットが参加しているグループでメンバーの参加・退出を再度行い、LangBot のイベント記録を確認します。
+
+メンバーの参加・退出を受信するには、ボットが対象グループに参加し、次のイベントを購読している必要があります。
+
+| 機能 | Feishu イベント |
+| --- | --- |
+| ユーザーのグループ参加 | `im.chat.member.user.added_v1` |
+| ユーザーの退出・グループからの削除 | `im.chat.member.user.deleted_v1` |
+
+ボット自身の参加（`im.chat.member.bot.added_v1`）は別のイベントで、他のメンバーの参加・退出は含まれません。LangBot の**イベントルーティング**でも、対象イベントを Agent またはプラグイン処理器に振り分けてください。パイプラインはメッセージイベントのみを処理します。
+
 ---

 ## ボットの作成
@@ -41,12 +41,38 @@ LangBot 支持一键创建飞书应用并自动填写凭证，无需手动复制

 ![配置成功](/images/zh/deploy/bots/lark/lark_config_success.png)

-7. **手动填写机器人名称**，名称必须与飞书机器人名称一致，否则机器人将无法在群内正常接收消息
+7. 新版适配器会自动获取机器人身份，无需填写用于识别群内 @ 的机器人名称。如果使用旧版适配器且仍显示该字段，请填写与飞书机器人一致的名称。

 ![手动填写机器人名称](/images/zh/deploy/bots/lark/lark_fill_bot_name.png)

 8. 点击**提交**，完成创建

+### 补充权限和事件订阅
+
+<Note>
+扫码创建或授权应用后，应用权限和事件订阅可能尚未覆盖你要使用的全部功能。能正常收发消息，不代表已经订阅了成员进退群等事件。无需重新创建机器人，可以到开发者平台为现有应用补充配置。
+</Note>
+
+1. 打开[飞书开发者平台](https://open.feishu.cn/app)（海外版使用 [Lark 开发者平台](https://open.larksuite.com/app)），选择扫码时创建或授权的应用，可通过 App ID 核对。
+2. 在**权限管理**中，按需要添加功能所需的权限。应用权限决定机器人可以读取哪些数据、执行哪些操作。
+3. 在**事件与回调 > 事件配置**中，添加需要接收的事件。事件订阅决定飞书会向 LangBot 推送哪些通知；仅添加权限不会自动订阅事件。
+4. 按平台提示保存配置，并完成所需的版本发布或管理员审批。配置生效后，再触发一次事件验证，之前的操作不会因补充订阅而自动重放。
+
+<Warning>
+**添加事件后，别忘记发布应用新版本。** 在开发者平台的**版本管理与发布**中完成发布；如需管理员审批，还需等待审批通过。仅在配置页添加并保存事件，待发布的配置尚未生效，即使 LangBot 显示连接正常，也可能收不到这些事件。
+</Warning>
+
+如果添加订阅后仍收不到成员进退群等事件，先检查应用是否还有**待发布或待审批**的变更。确认新版本生效后，在机器人所在群内重新操作一次成员进群或退群，再查看 LangBot 的事件记录。
+
+例如，监听群成员变化需要订阅以下两个事件，且机器人需要在对应群聊中：
+
+| 功能 | 飞书事件 |
+| --- | --- |
+| 用户进群 | `im.chat.member.user.added_v1` |
+| 用户主动退群或被移出群聊 | `im.chat.member.user.deleted_v1` |
+
+“机器人进群”是另一个事件（`im.chat.member.bot.added_v1`），只订阅它不会收到其他成员的进退群通知。订阅生效后，还需要在 LangBot 的**事件路由**中将对应事件交给 Agent 或插件处理器；流水线只处理消息事件。
+
 ---

 ## 手动配置