diff --git a/en/usage/platforms/slack.mdx b/en/usage/platforms/slack.mdx index 29ccb65b2..9219a87e3 100644 --- a/en/usage/platforms/slack.mdx +++ b/en/usage/platforms/slack.mdx @@ -4,7 +4,84 @@ description: "Build a Slack AI bot with LangBot. Connect GPT, Claude, Dify and m icon: "/images/platforms/slack.svg" --- -## Create Bot +## Quick setup (recommended) + +Use **Quick Slack setup** to create your app. LangBot configures bot scopes, message events, the messages tab and the OAuth return URL. You provide configuration tokens, approve installation in Slack, and add an App-Level Token when using Socket Mode. + +### 1. Create a bot and choose a connection mode + +In LangBot, open **Bots → Create bot**, enter a name, select **Slack**, and submit. On the configuration page, choose a connection mode and select **Quick Slack setup → Start**: + +![Create a bot and select the Slack adapter](/images/zh/deploy/bots/slack/setup-create-bot.jpg) + +- **Socket Mode (recommended)**: LangBot connects to Slack. No public event webhook is required, making this suitable for local or private-network deployments. +- **Webhook**: Slack sends events to LangBot through a publicly reachable HTTPS endpoint. + +![Select Socket Mode and open Quick Slack setup](/images/zh/deploy/bots/slack/setup-connection-mode.jpg) + +### 2. Get App Configuration Tokens + +Open the [Slack apps page](https://api.slack.com/apps). Under **Your App Configuration Tokens**, select **Generate Token** and choose the target workspace. Copy both the **Access Token** and **Refresh Token**. If tokens already exist, use their copy buttons. + +![Slack configuration token section and copy buttons](/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg) + +These tokens create and configure apps. **They are not the runtime Bot Token or App-Level Token.** Paste each into its matching field in the assistant and confirm the app name. + +### 3. Confirm the URL and create the app + +For Socket Mode, check the **OAuth return URL**. It returns your browser to LangBot after authorization, accepts HTTPS or `http://localhost`, and ends in `/api/v1/platform/adapters/slack/setup/callback`. Only your browser needs to reach it; this is not an event webhook. For remote deployments, do not use a server-internal address that your browser cannot reach. + +![Socket Mode quick setup form](/images/zh/deploy/bots/slack/setup-socket-mode.jpg) + +For Webhook, the assistant shows a **Webhook URL** instead. Verify the public domain, HTTPS and reverse proxy, and preserve the `/bots/` suffix. LangBot derives the OAuth return URL from it and completes Slack's event URL verification automatically. + +Select **Create and configure**, then wait for **Authorize in Slack**. + +### 4. Authorize installation in Slack + +Select **Authorize in Slack**, review the app name, workspace and permissions, and select **Allow**. Workspace policy may require administrator approval. Return to the original LangBot assistant afterward. + +![Slack installation authorization page](/images/zh/deploy/bots/slack/setup-slack-permissions.jpg) + +### 5. Socket Mode: add an App-Level Token + +Skip this step for Webhook. For Socket Mode, use **Open app settings** in the assistant and navigate to **Basic Information → App-Level Tokens → Generate Token and Scopes**: + +1. Enter a Token Name, such as `langbot-socket`. +2. Select **Add Scope**, then **connections:write**. +3. Select **Generate**, copy the resulting `xapp-` token, and paste it into **App-Level Token** in the assistant. + +![Add connections:write to the App-Level Token](/images/zh/deploy/bots/slack/setup-app-token-scope.jpg) + +Leave **Token rotation** disabled. The token must belong to the same Slack app you just created. Do not use the Access Token or Refresh Token from step 2 here. + +### 6. Fill configuration, set routing and enable the bot + +When the assistant reports successful authorization, select **Fill adapter configuration**. In Socket Mode, this button becomes available after you enter the App-Level Token. The assistant fills the Bot Token and other adapter credentials automatically. + +![Authorization completed and adapter configuration ready to fill](/images/zh/deploy/bots/slack/setup-authorized.jpg) + +Under **Event routing → Add action → Reply to received messages**, select a configured pipeline or Agent for `message.received` and keep the route enabled. Finally, select **Save and enable** at the top right. + +![Configure the message route and save the bot](/images/zh/deploy/bots/slack/setup-routing.jpg) + +### 7. Test a conversation + +Open the app's **Messages** tab in Slack and send a direct message. You can also invite the bot to a channel and mention it. A reply confirms the integration works. + +![A successful Slack bot conversation](/images/zh/deploy/bots/slack/setup-conversation.png) + + +Configuration tokens are used only during the temporary setup session, not saved as runtime credentials. Sessions last 15 minutes. Cancelling does not delete an app already created in Slack, and starting again may create another app. If the return page shows an error, check whether the original assistant already reports successful authorization before restarting. + + +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. + +## Manual setup (Webhook) + +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 Go to the [Slack App Platform](https://api.slack.com/apps). @@ -29,7 +106,7 @@ After adding the above permissions, click `Install to your workspace`, record th Enter the `App Home` tab on the left, scroll to the bottom where you'll find `Message Tab`, turn it on and check `Allow users to send Slash commands and messages from the messages tab`. -## Connect to LangBot +### Connect to LangBot Enter `Event Subscriptions` on the left, turn on the switch, click `Subscribe to bot events`, add the following permissions: @@ -39,10 +116,10 @@ After completing all the above operations, open the LangBot Webui configuration ![Event Permissions](/images/zh/deploy/bots/slack/connect_to_langbot.png) -## Start Bot +### Start Bot -Since Slack officially requires https, please configure reverse proxy first according to the documentation [Configure HTTP Reverse Proxy and SSL](/en/workshop/production/proxy-and-ssl). +Webhook mode requires public HTTPS; please configure reverse proxy first according to the documentation [Configure HTTP Reverse Proxy and SSL](/en/workshop/production/proxy-and-ssl). After filling in the Slack configuration items, **start LangBot**. @@ -52,6 +129,6 @@ Enable and open the Slack bot configuration page on the LangBot homepage, copy t After filling in all the above configuration items, click save link. If it shows a green **Verified**, it means the deployment is successful. Otherwise, check if the above configuration items are filled in correctly. -## Effect Demonstration +### Effect Demonstration ![Effect Demonstration](/images/zh/deploy/bots/slack/slack_05.jpg) diff --git a/images/zh/deploy/bots/slack/setup-app-token-scope.jpg b/images/zh/deploy/bots/slack/setup-app-token-scope.jpg new file mode 100644 index 000000000..bfd228cce Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-app-token-scope.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-authorized.jpg b/images/zh/deploy/bots/slack/setup-authorized.jpg new file mode 100644 index 000000000..bc8149861 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-authorized.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg b/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg new file mode 100644 index 000000000..b0038e7c1 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-connection-mode.jpg b/images/zh/deploy/bots/slack/setup-connection-mode.jpg new file mode 100644 index 000000000..7f81c5b82 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-connection-mode.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-conversation.png b/images/zh/deploy/bots/slack/setup-conversation.png new file mode 100644 index 000000000..363b67fa5 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-conversation.png differ diff --git a/images/zh/deploy/bots/slack/setup-create-bot.jpg b/images/zh/deploy/bots/slack/setup-create-bot.jpg new file mode 100644 index 000000000..e383986ba Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-create-bot.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-routing.jpg b/images/zh/deploy/bots/slack/setup-routing.jpg new file mode 100644 index 000000000..212491924 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-routing.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-slack-permissions.jpg b/images/zh/deploy/bots/slack/setup-slack-permissions.jpg new file mode 100644 index 000000000..2ab6cfd21 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-slack-permissions.jpg differ diff --git a/images/zh/deploy/bots/slack/setup-socket-mode.jpg b/images/zh/deploy/bots/slack/setup-socket-mode.jpg new file mode 100644 index 000000000..ed0b4f862 Binary files /dev/null and b/images/zh/deploy/bots/slack/setup-socket-mode.jpg differ diff --git a/ja/usage/platforms/slack.mdx b/ja/usage/platforms/slack.mdx index a752f6bc3..e84257858 100644 --- a/ja/usage/platforms/slack.mdx +++ b/ja/usage/platforms/slack.mdx @@ -4,7 +4,84 @@ description: "LangBot で Slack AI ボットを構築。GPT・Claude・Dify 等 icon: "/images/platforms/slack.svg" --- -## ボットの作成 +## クイック設定（推奨） + +**Slack クイック設定**を使うと、LangBot がアプリの権限、メッセージイベント、メッセージタブ、OAuth 戻り先 URL を自動設定します。設定トークンを入力して Slack でインストールを承認し、Socket Mode の場合は App-Level Token を追加してください。 + +### 1. ボットを作成して接続方式を選ぶ + +LangBot の **ボット → ボットを作成**で名前を入力し、**Slack** を選んで送信します。設定ページで接続方式を選び、**Slack クイック設定 → 開始**をクリックします。 + +![ボットを作成して Slack アダプターを選択する](/images/zh/deploy/bots/slack/setup-create-bot.jpg) + +- **Socket Mode（推奨）**：LangBot から Slack に接続するため、公開イベント Webhook は不要です。ローカル環境やプライベートネットワークに適しています。 +- **Webhook**：Slack がイベントを送信するため、公開 HTTPS エンドポイントが必要です。 + +![Socket Mode を選びクイック設定を開く](/images/zh/deploy/bots/slack/setup-connection-mode.jpg) + +### 2. App Configuration Tokens を取得する + +[Slack アプリページ](https://api.slack.com/apps)を開き、**Your App Configuration Tokens → Generate Token** で対象のワークスペースを選択します。**Access Token** と **Refresh Token** をそれぞれコピーしてください。既存のトークンがある場合は、そのコピー用ボタンを使用できます。 + +![設定トークンの場所とコピーボタン](/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg) + +これらはアプリの作成・設定用であり、**実行時に使う Bot Token や App-Level Token とは異なります**。アシスタントの対応する欄に入力し、アプリ名を確認します。 + +### 3. URL を確認してアプリを自動作成する + +Socket Mode では **OAuth 戻り先 URL** を確認します。承認後にブラウザーを LangBot に戻す URL で、HTTPS または `http://localhost` を使用でき、末尾は `/api/v1/platform/adapters/slack/setup/callback` です。ブラウザーからアクセスできればよく、イベント Webhook ではありません。リモート環境では、ブラウザーから到達できないサーバー内部のアドレスを指定しないでください。 + +![Socket Mode のクイック設定フォーム](/images/zh/deploy/bots/slack/setup-socket-mode.jpg) + +Webhook の場合は **Webhook URL** が表示されます。公開ドメイン、HTTPS、リバースプロキシを確認し、末尾の `/bots/<ボット UUID>` を維持してください。この URL から OAuth 戻り先 URL が生成され、Slack のイベント URL 検証も自動で行われます。 + +**作成して自動設定**をクリックし、**Slack で承認**が表示されるまで待ちます。 + +### 4. Slack でインストールを承認する + +**Slack で承認**を開き、アプリ名、ワークスペース、権限を確認して **Allow** をクリックします。ワークスペースのポリシーによっては管理者の承認が必要です。完了後、元の LangBot アシスタントに戻ります。 + +![Slack のインストール承認画面](/images/zh/deploy/bots/slack/setup-slack-permissions.jpg) + +### 5. Socket Mode：App-Level Token を追加する + +Webhook の場合はこの手順をスキップします。Socket Mode ではアシスタントの**アプリ設定を開く**から **Basic Information → App-Level Tokens → Generate Token and Scopes** に進みます。 + +1. Token Name に `langbot-socket` などの名前を入力します。 +2. **Add Scope** で **connections:write** を選択します。 +3. **Generate** をクリックし、生成された `xapp-` トークンをコピーして、アシスタントの **App-Level Token** に入力します。 + +![App-Level Token に connections:write を追加する](/images/zh/deploy/bots/slack/setup-app-token-scope.jpg) + +**Token rotation** は無効のままにしてください。作成した同じ Slack アプリのトークンを使用します。手順 2 の Access Token や Refresh Token をここに入力しないでください。 + +### 6. 設定を反映し、ルーティングを設定して有効化する + +承認完了が表示されたら、**アダプター設定に入力**をクリックします。Socket Mode では App-Level Token を入力すると、このボタンが有効になります。Bot Token などの認証情報は自動で反映されます。 + +![承認完了とアダプター設定への反映](/images/zh/deploy/bots/slack/setup-authorized.jpg) + +**イベントルーティング → アクションを追加 → 受信メッセージに返信**で、`message.received` に設定済みのパイプラインまたは Agent を指定し、ルートを有効にします。最後に右上の**保存して有効化**をクリックします。 + +![メッセージのルートを設定して保存する](/images/zh/deploy/bots/slack/setup-routing.jpg) + +### 7. 会話を確認する + +Slack でアプリの **Messages** タブを開き、DM を送信します。ボットをチャンネルに招待してメンションすることもできます。返信が届けば接続成功です。 + +![Slack ボットとの会話成功例](/images/zh/deploy/bots/slack/setup-conversation.png) + + +設定トークンは一時的な設定セッションでのみ使用し、実行用の認証情報として保存しません。セッションは 15 分間有効です。キャンセルしても作成済みの Slack アプリは削除されず、再実行すると別のアプリが作成される場合があります。戻り先ページでエラーが出ても、最初に元のアシスタントで承認完了になっていないか確認してください。 + + +返信がない場合は、ボットとメッセージルートが有効か、処理先が正常に動作するか、ボットのログにエラーがないかを確認します。Socket Mode では同じアプリの App-Level Token と `connections:write` 権限を、Webhook では公開 URL と Slack の **Verified** 表示を確認してください。 + +## 手動設定（Webhook） + +以下は手動 Webhook 設定です。手動で Socket Mode を使う場合は Slack 側で有効にし、Bot Token と App-Level Token を入力して `app_mention` と `message.im` を購読します。イベント Request URL は不要です。 + +### ボットの作成 [Slack App Platform](https://api.slack.com/apps)にアクセスします。 @@ -29,7 +106,7 @@ icon: "/images/platforms/slack.svg" 左側の「App Home」タブに入り、一番下までスクロールして「Message Tab」を見つけ、オンにして 「Allow users to send Slash commands and messages from the messages tab」をチェックします。 -## LangBot に接続 +### LangBot に接続 左側の「Event Subscriptions」に入り、スイッチをオンにし、「Subscribe to bot events」をクリックし、 次の権限を追加します： @@ -39,10 +116,10 @@ icon: "/images/platforms/slack.svg" ![Event Permissions](/images/zh/deploy/bots/slack/connect_to_langbot.png) -## ボットの起動 +### ボットの起動 -Slack 公式が https を要求しているため、まずドキュメント [HTTP リバースプロキシと SSL の設定](/en/workshop/production/proxy-and-ssl)に従ってリバースプロキシを設定してください。 +Webhook には公開 HTTPS URL が必要なため、まずドキュメント [HTTP リバースプロキシと SSL の設定](/en/workshop/production/proxy-and-ssl)に従ってリバースプロキシを設定してください。 Slack 設定項目を入力した後、**LangBot を起動します**。 @@ -52,6 +129,6 @@ LangBot ホームページで Slack ボットを有効にして開き、ボッ 上記のすべての設定項目を入力した後、リンクを保存をクリックします。緑色の **Verified** が表示されれば、デプロイは成功です。 それ以外の場合は、上記の設定項目が正しく入力されているかどうかを確認してください。 -## 効果のデモンストレーション +### 効果のデモンストレーション ![Effect Demonstration](/images/zh/deploy/bots/slack/slack_05.jpg) diff --git a/zh/usage/platforms/slack.mdx b/zh/usage/platforms/slack.mdx index 0751f32ed..b7b76e057 100644 --- a/zh/usage/platforms/slack.mdx +++ b/zh/usage/platforms/slack.mdx @@ -4,7 +4,84 @@ description: "用 LangBot 搭建 Slack AI 机器人，将 GPT、Claude、Dify icon: "/images/platforms/slack.svg" --- -## 创建机器人 +## 快速配置（推荐） + +推荐使用 **Slack 快速配置** 创建应用。LangBot 会自动配置机器人权限、消息事件、消息页和 OAuth 返回地址；你只需提供配置令牌、在 Slack 确认安装，并在长连接模式下补充 App-Level Token。 + +### 1. 创建机器人并选择接入方式 + +在 LangBot 的 **机器人 → 创建机器人** 中填写名称，选择 **Slack**，提交后进入配置页。选择接入方式，然后点击 **Slack 快速配置 → 开始**： + +![创建机器人并选择 Slack 适配器](/images/zh/deploy/bots/slack/setup-create-bot.jpg) + +- **长连接（Socket Mode，推荐）**：LangBot 主动连接 Slack，无需公网事件 Webhook，适合本地或内网部署。 +- **Webhook**：Slack 向 LangBot 推送事件，需要可从公网访问的 HTTPS 地址。 + +![选择长连接并打开 Slack 快速配置](/images/zh/deploy/bots/slack/setup-connection-mode.jpg) + +### 2. 获取 App Configuration Tokens + +打开 [Slack 应用页面](https://api.slack.com/apps)，找到 **Your App Configuration Tokens**，点击 **Generate Token**，选择目标工作区。分别复制 **Access Token** 和 **Refresh Token**；已有令牌时，可以直接使用对应的复制按钮。 + +![Slack 配置令牌入口与复制按钮](/images/zh/deploy/bots/slack/setup-configuration-tokens.jpg) + +这两个令牌用于创建和配置应用，**不是机器人运行时使用的 Bot Token 或 App-Level Token**。在助手中分别填入对应字段，并确认应用名称。 + +### 3. 确认地址并自动创建应用 + +长连接模式下，确认 **OAuth 授权返回地址**。它用于授权完成后让浏览器返回 LangBot，支持 HTTPS 或 `http://localhost`，末尾为 `/api/v1/platform/adapters/slack/setup/callback`。只需你的浏览器能访问这个地址；它不是接收消息的 Webhook。远程部署时，不要填写浏览器所在电脑无法访问的服务器内部地址。 + +![长连接快速配置表单](/images/zh/deploy/bots/slack/setup-socket-mode.jpg) + +Webhook 模式下，助手显示的是 **Webhook 回调地址**。确认域名、HTTPS 和反向代理均可用，保留 `/bots/<机器人 UUID>` 后缀。LangBot 会从该地址生成 OAuth 返回地址，并自动完成 Slack 的事件地址验证。 + +点击 **创建并自动配置**，等待出现 **前往 Slack 授权**。 + +### 4. 在 Slack 安装授权 + +点击 **前往 Slack 授权**，核对应用名称、工作区和权限，然后点击 **Allow**。工作区策略可能要求管理员批准。完成后返回原来的 LangBot 配置助手。 + +![Slack 安装授权页面](/images/zh/deploy/bots/slack/setup-slack-permissions.jpg) + +### 5. 长连接模式：补充 App-Level Token + +Webhook 模式可跳过本步。长连接模式中，点击助手的 **打开应用设置**，进入 **Basic Information → App-Level Tokens → Generate Token and Scopes**： + +1. 填写 Token Name，例如 `langbot-socket`。 +2. 点击 **Add Scope**，选择 **connections:write**。 +3. 点击 **Generate**，复制生成的 `xapp-` 令牌，填回助手的 **App-Level Token**。 + +![为 App-Level Token 添加 connections:write 权限](/images/zh/deploy/bots/slack/setup-app-token-scope.jpg) + +不需要开启 **Token rotation**。这里必须使用刚创建的同一个 Slack 应用的令牌，不能填入第 2 步的 Access Token 或 Refresh Token。 + +### 6. 回填配置、设置路由并启用 + +助手显示 **授权完成** 后，点击 **填入适配器配置**。长连接模式需先填入 App-Level Token，此按钮才可用。Bot Token 等适配器凭据会自动回填。 + +![授权完成并回填适配器配置](/images/zh/deploy/bots/slack/setup-authorized.jpg) + +在 **事件路由 → 添加行为 → 回复收到的消息** 中，为 `message.received` 选择已配置好的流水线或 Agent，并保持该路由启用。最后点击页面右上角 **保存并启用**。 + +![配置收到消息的路由并保存启用](/images/zh/deploy/bots/slack/setup-routing.jpg) + +### 7. 验证对话 + +在 Slack 中打开应用的 **Messages** 页面，发送一条私聊消息。也可以将机器人加入频道后 @ 它。收到回复即表示接入成功。 + +![Slack 机器人成功回复消息](/images/zh/deploy/bots/slack/setup-conversation.png) + + +配置令牌仅在短期配置会话中使用，不作为机器人运行凭据保存。会话有效期为 15 分钟；取消助手不会删除已创建的 Slack 应用。重新开始可能创建另一个应用，请勿因为授权返回页显示异常就反复创建，先检查原助手是否已显示“授权完成”。 + + +如果没有回复，先确认机器人及消息路由已启用、处理器本身能够正常运行，并查看机器人日志。长连接模式检查 App-Level Token 是否属于同一应用且包含 `connections:write`；Webhook 模式检查公网地址和 Slack 的 **Verified** 状态。 + +## 手动配置（Webhook） + +下面保留手动 Webhook 配置步骤。若手动使用长连接，请在 Slack 开启 Socket Mode，填写 Bot Token 和 App-Level Token，并订阅 `app_mention` 和 `message.im`；无需配置事件 Request URL。 + +### 创建机器人 前往 [Slack的App平台](https://api.slack.com/apps)。 @@ -30,7 +107,7 @@ icon: "/images/platforms/slack.svg" 进入左侧 `App Home` 栏，滑到最下面有 `Message Tab`，打开并且勾选 `Allow users to send Slash commands and messages from the messages tab`。 -## 对接 LangBot +### 对接 LangBot 进入左侧 `Event Subscriptions` ，打开开关，点击 `Subscribe to bot events`， 将如下权限添加进去: @@ -40,10 +117,10 @@ icon: "/images/platforms/slack.svg" ![事件权限](/images/zh/deploy/bots/slack/connect_to_langbot.png) -## 启动机器人 +### 启动机器人 -由于 Slack 官方要求使用 https，请根据文档[配置 HTTP 反向代理和 SSL](/zh/workshop/production/proxy-and-ssl) 先配置好反向代理。 +Webhook 模式要求公网 HTTPS 地址，请根据文档[配置 HTTP 反向代理和 SSL](/zh/workshop/production/proxy-and-ssl) 先配置好反向代理。 Slack 配置项在填写完成后，**启动 LangBot**。 @@ -53,6 +130,6 @@ Slack 配置项在填写完成后，**启动 LangBot**。 上述配置项都填写完成后，点击保存链接，若标识为绿色的**Verified**，那么就说明部署成功。 否则查看上述配置项是否填写正确。 -## 效果图 +### 效果图 ![效果图](/images/zh/deploy/bots/slack/slack_05.jpg)