From cf9beff70958f9e39ac1111bd6291a81cfee1c4d Mon Sep 17 00:00:00 2001 From: Hyu Date: Sun, 11 Oct 2026 00:17:38 +0800 Subject: [PATCH] docs(slack): document event subscriptions and existing app upgrades --- en/usage/platforms/slack.mdx | 30 ++++++++++++++++++++++++++++++ ja/usage/platforms/slack.mdx | 30 ++++++++++++++++++++++++++++++ zh/usage/platforms/slack.mdx | 30 ++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+) diff --git a/en/usage/platforms/slack.mdx b/en/usage/platforms/slack.mdx index 9219a87e3..58c1924ef 100644 --- a/en/usage/platforms/slack.mdx +++ b/en/usage/platforms/slack.mdx @@ -77,8 +77,38 @@ Configuration tokens are used only during the temporary setup session, not saved If no reply arrives, check that both the bot and message route are enabled, the handler works, and the bot logs show no errors. For Socket Mode, verify that the App-Level Token belongs to the same app and includes `connections:write`. For Webhook, check the public endpoint and Slack's **Verified** status. +## Events, interactions and upgrading existing apps + +Quick setup configures the subscriptions and interaction endpoint below. Installation requests message, channel, user, file and reaction permissions; `reactions:read` enables reaction events. Normal channel replies still require an @mention. Subscribing to channel messages for edits, deletions and channel changes does not trigger replies to all channel traffic. + +| Slack event | LangBot event | +| --- | --- | +| Direct messages, `app_mention` | `message.received` | +| `message_changed` / `message_deleted` message subtypes | `message.edited` / `message.deleted` | +| `reaction_added` / `reaction_removed` | `message.reaction`, distinguished by `is_add` | +| `member_joined_channel` / `member_left_channel` | `group.member_joined` / `group.member_left` | +| Membership events for the bot itself | `bot.invited_to_group` when an inviter is present; `bot.removed_from_group` on departure | +| Channel rename, archive/unarchive, topic/purpose changes | `group.info_updated` | +| `block_actions`, `view_submission`, `view_closed`, `shortcut`, `message_action` | `platform.specific`, with `action` set to `slack.` plus the callback type | +| `app_home_opened`, `app_uninstalled`, `tokens_revoked` | `platform.specific`, with `action` set to `slack.` plus the event type | + +Configure handlers in the bot's event routing; distinguish platform callbacks by `action`. Uninstallation and token revocation also produce bot warning logs and do not automatically send chat replies. Emoji reactions are not automatically treated as model feedback. Message IDs use Slack message timestamps (`ts`) together with the channel; replies preserve `thread_ts`. + +Interactions are acknowledged first and processed asynchronously. Synchronous field validation errors in modal submission acknowledgements and external select-option loading are not supported. Set `notify_on_close: true` when opening a modal to receive `view_closed`. Receiving callbacks does not create buttons, shortcuts or modals. Both Socket Mode and Webhook support these handlers; actual delivery depends on Slack permissions, channel membership and connection availability. + +**Upgrading LangBot does not automatically update an existing Slack app's permissions.** Keep the existing app and: + +1. In **OAuth & Permissions → Bot Token Scopes**, retain existing scopes and add `reactions:read`. Verify `app_mentions:read`, `chat:write`, `channels:history`, `channels:read`, `groups:history`, `groups:read`, `im:history`, `im:read`, `im:write`, `mpim:history`, `mpim:read`, `users:read`, `files:read`, `files:write`, then **Reinstall to Workspace** to authorize the permissions. +2. In **Event Subscriptions → Subscribe to bot events**, configure: `app_mention`, `message.im`, `message.channels`, `message.groups`, `message.mpim`, `reaction_added`, `reaction_removed`, `member_joined_channel`, `member_left_channel`, `channel_rename`, `group_rename`, `channel_archive`, `channel_unarchive`, `group_archive`, `group_unarchive`, `app_home_opened`, `app_uninstalled`, `tokens_revoked`. Edits/deletions and topic/purpose changes are message subtypes, not separate subscriptions. +3. Enable **Interactivity & Shortcuts**. For Webhook, use the same LangBot `/bots/` **Request URL** as event subscriptions. Socket Mode needs no public interaction URL. +4. Save Slack settings and configure the corresponding LangBot routes. If reinstallation changes the Bot Token, update it and save the bot. + +See the [Slack App Manifest reference](https://docs.slack.dev/reference/app-manifest/) for field definitions. + ## Manual setup (Webhook) +The screenshots below show basic messaging setup. Use the current lists in “Events, interactions and upgrading existing apps” above for complete permissions, subscriptions and interactivity settings. + The manual Webhook instructions follow. For manual Socket Mode setup, enable Socket Mode in Slack, supply Bot Token and App-Level Token, and subscribe to `app_mention` and `message.im`. No event Request URL is needed. ### Create Bot diff --git a/ja/usage/platforms/slack.mdx b/ja/usage/platforms/slack.mdx index e84257858..e5267433f 100644 --- a/ja/usage/platforms/slack.mdx +++ b/ja/usage/platforms/slack.mdx @@ -77,8 +77,38 @@ Slack でアプリの **Messages** タブを開き、DM を送信します。ボ 返信がない場合は、ボットとメッセージルートが有効か、処理先が正常に動作するか、ボットのログにエラーがないかを確認します。Socket Mode では同じアプリの App-Level Token と `connections:write` 権限を、Webhook では公開 URL と Slack の **Verified** 表示を確認してください。 +## イベント、インタラクション、既存アプリの更新 + +クイック設定は以下の購読とインタラクションの受信設定を行います。インストール時にメッセージ、チャンネル、ユーザー、ファイル、リアクションの権限を要求し、リアクションには `reactions:read` を使用します。チャンネルの通常返信には引き続き @メンションが必要です。編集・削除やチャンネル変更のためのメッセージ購読によって、すべての会話に返信することはありません。 + +| Slack イベント | LangBot イベント | +| --- | --- | +| DM、`app_mention` | `message.received` | +| `message_changed` / `message_deleted` サブタイプ | `message.edited` / `message.deleted` | +| `reaction_added` / `reaction_removed` | `message.reaction`、`is_add` で区別 | +| `member_joined_channel` / `member_left_channel` | `group.member_joined` / `group.member_left` | +| ボット自身の参加・退出 | 招待者がある場合は `bot.invited_to_group`、退出は `bot.removed_from_group` | +| チャンネル名、アーカイブ状態、トピック・用途の変更 | `group.info_updated` | +| `block_actions`、`view_submission`、`view_closed`、`shortcut`、`message_action` | `platform.specific`、`action` は `slack.` とコールバック名 | +| `app_home_opened`、`app_uninstalled`、`tokens_revoked` | `platform.specific`、`action` は `slack.` とイベント名 | + +ボットのイベントルーティングでハンドラーを設定し、プラットフォームイベントは `action` で区別します。アンインストールとトークン失効は警告ログにも記録され、自動でチャット返信しません。リアクションをモデルへの評価とは自動判定しません。メッセージ ID は Slack の `ts` をチャンネルと組み合わせて識別し、スレッド返信は `thread_ts` を維持します。 + +インタラクションは受信確認後に非同期処理します。モーダル送信の確認応答での同期的な項目エラー返却と外部選択肢の読み込みには対応していません。`view_closed` を受信するにはモーダル作成時に `notify_on_close: true` が必要です。ボタン、ショートカット、モーダル自体は自動作成しません。Socket Mode と Webhook の両方で受信できますが、配信は Slack の権限、チャンネルへの参加、接続状態に依存します。 + +**LangBot の更新だけでは既存 Slack アプリの権限は更新されません。** アプリを作り直さず、次の設定を追加してください。 + +1. **OAuth & Permissions → Bot Token Scopes** で既存権限を維持し、`reactions:read` を追加します。`app_mentions:read`、`chat:write`、`channels:history`、`channels:read`、`groups:history`、`groups:read`、`im:history`、`im:read`、`im:write`、`mpim:history`、`mpim:read`、`users:read`、`files:read`、`files:write` を確認し、**Reinstall to Workspace** で再承認します。 +2. **Event Subscriptions → Subscribe to bot events** に `app_mention`、`message.im`、`message.channels`、`message.groups`、`message.mpim`、`reaction_added`、`reaction_removed`、`member_joined_channel`、`member_left_channel`、`channel_rename`、`group_rename`、`channel_archive`、`channel_unarchive`、`group_archive`、`group_unarchive`、`app_home_opened`、`app_uninstalled`、`tokens_revoked` を設定します。編集・削除とトピック・用途変更はメッセージのサブタイプであり、個別の購読は不要です。 +3. **Interactivity & Shortcuts** を有効にします。Webhook の **Request URL** はイベント購読と同じ LangBot `/bots/<ボット UUID>` を指定します。Socket Mode では公開インタラクション URL は不要です。 +4. Slack の設定を保存し、LangBot のイベントルートを設定します。再インストールで Bot Token が変わった場合は更新してボットを保存してください。 + +各フィールドは [Slack App Manifest リファレンス](https://docs.slack.dev/reference/app-manifest/)を参照してください。 + ## 手動設定（Webhook） +以下の画像は基本的な会話設定です。権限、イベント購読、インタラクションの完全な設定は、上の「イベント、インタラクション、既存アプリの更新」の最新リストを使用してください。 + 以下は手動 Webhook 設定です。手動で Socket Mode を使う場合は Slack 側で有効にし、Bot Token と App-Level Token を入力して `app_mention` と `message.im` を購読します。イベント Request URL は不要です。 ### ボットの作成 diff --git a/zh/usage/platforms/slack.mdx b/zh/usage/platforms/slack.mdx index b7b76e057..ee8284835 100644 --- a/zh/usage/platforms/slack.mdx +++ b/zh/usage/platforms/slack.mdx @@ -77,8 +77,38 @@ Webhook 模式可跳过本步。长连接模式中，点击助手的 **打开应 如果没有回复，先确认机器人及消息路由已启用、处理器本身能够正常运行，并查看机器人日志。长连接模式检查 App-Level Token 是否属于同一应用且包含 `connections:write`；Webhook 模式检查公网地址和 Slack 的 **Verified** 状态。 +## 事件、交互与已有应用升级 + +新版快速配置向导会自动配置下列事件订阅和交互入口。安装授权页会申请消息、频道、用户、文件和表情反应权限，其中 `reactions:read` 用于表情反应事件。频道中的普通回复仍只由 @ 机器人触发；为获取编辑、删除和频道信息变化而订阅的频道消息不会全部触发回复。 + +| Slack 事件 | LangBot 事件 | +| --- | --- | +| 私聊消息、`app_mention` | `message.received` | +| `message_changed` / `message_deleted` 消息子类型 | `message.edited` / `message.deleted` | +| `reaction_added` / `reaction_removed` | `message.reaction`，通过 `is_add` 区分 | +| `member_joined_channel` / `member_left_channel` | `group.member_joined` / `group.member_left` | +| 上述成员事件中的机器人自身 | 有邀请者时为 `bot.invited_to_group`；离开时为 `bot.removed_from_group` | +| 频道重命名、归档/取消归档、主题/用途变化 | `group.info_updated` | +| `block_actions`、`view_submission`、`view_closed`、`shortcut`、`message_action` | `platform.specific`，`action` 为 `slack.` 加回调类型 | +| `app_home_opened`、`app_uninstalled`、`tokens_revoked` | `platform.specific`，`action` 为 `slack.` 加事件类型 | + +在机器人的事件路由中为所需事件配置处理器；平台事件可按 `action` 区分。卸载和令牌撤销同时写入机器人警告日志，不自动发送聊天回复。表情反应是普通反应事件，不自动视为对模型的反馈。消息 ID 使用 Slack 消息时间戳 `ts`，需结合频道识别；线程回复保留 `thread_ts`。 + +交互回调先确认接收，再异步交给处理器；目前不支持在表单提交确认中同步返回字段校验错误，也不提供外部下拉选项加载。接收 `view_closed` 需要创建弹窗时设置 `notify_on_close: true`。回调不会自动创建按钮、快捷方式或弹窗。Socket Mode 和 Webhook 均支持上述接收逻辑，但实际投递受 Slack 授权、频道成员关系及连接状态限制。 + +**已有应用不会因升级 LangBot 自动获得新权限。** 无需重新创建应用，按以下步骤补齐： + +1. 在 **OAuth & Permissions → Bot Token Scopes** 保留原权限，增加 `reactions:read`；确认包含 `app_mentions:read`、`chat:write`、`channels:history`、`channels:read`、`groups:history`、`groups:read`、`im:history`、`im:read`、`im:write`、`mpim:history`、`mpim:read`、`users:read`、`files:read`、`files:write`，然后 **Reinstall to Workspace** 重新授权。 +2. 在 **Event Subscriptions → Subscribe to bot events** 配置：`app_mention`、`message.im`、`message.channels`、`message.groups`、`message.mpim`、`reaction_added`、`reaction_removed`、`member_joined_channel`、`member_left_channel`、`channel_rename`、`group_rename`、`channel_archive`、`channel_unarchive`、`group_archive`、`group_unarchive`、`app_home_opened`、`app_uninstalled`、`tokens_revoked`。编辑/删除、主题/用途变化属于消息子类型，无需单独订阅。 +3. 在 **Interactivity & Shortcuts** 启用交互。Webhook 模式的 **Request URL** 与事件订阅使用同一个 LangBot `/bots/<机器人 UUID>` 地址；Socket Mode 不需要公网交互地址。 +4. 保存 Slack 设置，在 LangBot 配置相应事件路由。若重新安装后 Bot Token 改变，回填新值并保存机器人。 + +字段定义参考 [Slack App Manifest](https://docs.slack.dev/reference/app-manifest/)。 + ## 手动配置（Webhook） +下方截图展示基础对话配置；完整权限、事件订阅和交互配置请使用上方“事件、交互与已有应用升级”中的最新清单。 + 下面保留手动 Webhook 配置步骤。若手动使用长连接，请在 Slack 开启 Socket Mode，填写 Bot Token 和 App-Level Token，并订阅 `app_mention` 和 `message.im`；无需配置事件 Request URL。 ### 创建机器人