Slack 应用
为自托管实例创建 Warmbly for Slack 所需的 Slack 应用，配置应用清单、请求 URL、权限范围、事件和环境变量。
Warmbly for Slack 中的 Slack 助手、收件箱频道，以及频道和私信通知，都通过 Slack 应用运行。Warmbly Cloud 使用 Warmbly 自己的应用。自托管实例需要创建自己的应用，因为 Slack 会把一个应用的所有事件和按钮操作发送到该应用配置中的同一组请求 URL。一个 Slack 应用不能服务两个实例。
在设置应用凭据之前，控制台的 Slack 面板会显示尚未配置，Slack 请求 URL 则返回 503 和 slack_not_configured。
网络要求
| 功能 | 网络要求 |
|---|---|
| 连接 Slack、发布通知和收件箱回复 | 仅需能够出站通过 HTTPS 访问 slack.com |
| 助手、收件箱按钮、主页选项卡 | Slack 能通过公网 HTTPS 访问后端请求 URL，且证书受 Slack 信任 |
仅能通过私有网络访问的实例仍可向 Slack 发消息。所有交互功能都需要后端具有公开地址。
创建应用
填写应用清单
从仓库或你正在运行的版本中取出 deploy/slack/manifest.json，将所有 https://YOUR-BACKEND-HOST 替换为后端公开 URL，例如 https://api.example.com。这会填好请求 URL中列出的三个地址。
根据清单创建应用
在 api.slack.com/apps 选择 Create New App > From a manifest（创建新应用 > 从清单创建），选择要创建应用的 Slack 工作区，粘贴清单，检查后创建。
复制凭据
在新应用的 Basic Information（基本信息） 页面，找到 App Credentials（应用凭据），将 Client ID（客户端 ID）、Client Secret（客户端密钥） 和 Signing Secret（签名密钥） 复制到安装根目录的 .env 中：
SLACK_OAUTH_CLIENT_ID=1234567890.1234567890
SLACK_OAUTH_CLIENT_SECRET=...
SLACK_SIGNING_SECRET=...三个值都需要配置到后端和消费者。随项目提供的 docker-compose.yml 会将它们传给两个服务，.env.example 也列出了这些变量。清单中的主机必须与你的 API_PUBLIC_URL 一致，安装时已经设置了该值。然后重启两个服务。
验证事件 URL
Slack 会发送挑战请求检查事件 URL，后端只会响应能通过签名密钥验证的挑战。如果创建应用时 Slack 将 URL 标为未验证，现在密钥已设置，可以打开 Event Subscriptions（事件订阅） 并选择 Retry（重试）。
请求 URL
所有地址都基于后端公开 URL，即 API_PUBLIC_URL；设置了 BACKEND_PUBLIC_URL 时则使用后者。它必须与清单中的主机一致。
| Slack 设置 | URL |
|---|---|
| Event Subscriptions（事件订阅） 请求 URL | https://<backend>/api/v1/integrations/slack/events |
| Interactivity & Shortcuts（交互与快捷操作） 请求 URL | https://<backend>/api/v1/integrations/slack/interactivity |
| OAuth & Permissions（OAuth 与权限） 重定向 URL | https://<backend>/integrations/oauth/callback，设置了 INTEGRATIONS_OAUTH_REDIRECT_URL 时使用该值 |
相同的重定向 URL 也用于“使用 Slack 登录”，让成员关联邮箱地址与 Warmbly 不同的 Slack 账户。无需额外权限范围或设置。
Slack 发来的每个请求都会使用签名密钥检查：签名必须匹配，时间戳必须在五分钟内，请求体最多 1 MiB。验证失败返回 401，且不解析其中任何内容。所有请求都会在 Slack 的三秒限制内响应，随后再执行由它启动的工作。
如果后端公开 URL 改变，请在 Slack 应用中更新这些地址，或使用新主机的清单重新创建应用并替换凭据，同时更新 API_PUBLIC_URL。
权限范围
清单只请求以下机器人权限范围，没有用户权限范围：应用绝不会以 Slack 用户身份操作。
| 权限范围 | 用途 |
|---|---|
app_mentions:read | 接收频道中的 @Warmbly 提及 |
assistant:write | 运行助手面板，包括状态行和建议提示词 |
channels:history | 读取助手正在回复的公共频道会话中的后续回复，以及在会话内提及机器人时读取此前消息 |
channels:read | 为频道选择器列出公共频道，并判断频道是否与其他组织共享 |
chat:write | 发布通知、收件箱会话、答案和审批卡片 |
chat:write.public | 向机器人尚未加入的公共频道发布通知 |
commands | 提供就此询问 Warmbly消息快捷操作 |
groups:history | 与 channels:history 相同，但用于机器人受邀加入的私有频道 |
groups:read | 为频道选择器列出机器人已加入的私有频道 |
im:history | 读取发给机器人的私信 |
im:read | 识别机器人参与的私信会话 |
im:write | 打开私信，发送关联按钮、关联确认和个人通知 |
mpim:history | 在群组私信中提及机器人时，读取该会话此前的消息 |
reactions:write | 对正在处理的消息添加 👀 表情，并用 ✅ 标记完成 |
users:read | 显示关联按钮所关联 Slack 账户的姓名和头像 |
users:read.email | 读取该账户邮箱，必须与确认关联的 Warmbly 账户匹配 |
在应用新增权限范围之前已完成的安装，会继续使用现有权限。控制台会列出缺失范围并提供重新连接；需要这些权限的功能在重新连接之前保持关闭。
事件与功能
应用订阅以下机器人事件：
| 事件 | 用途 |
|---|---|
app_mention | 频道中的提问，包括收件箱会话线程中的提问 |
message.im | 私信中的提问或追问 |
message.channels、message.groups | 助手正在回复的线程中的追问。其他频道消息全部忽略，包括收件箱线程中的团队讨论 |
assistant_thread_started、assistant_thread_context_changed | 助手面板打开，以及面板打开时当前查看的频道发生变化 |
app_home_opened | 绘制主页选项卡 |
app_uninstalled、tokens_revoked | 应用移除或令牌撤销时，停止使用对应 Slack 工作区连接 |
它还会启用 Home（主页） 和 Messages（消息） 选项卡、带建议提示词的助手视图，以及就此询问 Warmbly消息快捷操作，回调为 ask_warmbly_about_message。
环境变量
| 变量 | 来源 | 作用 |
|---|---|---|
SLACK_OAUTH_CLIENT_ID | Basic Information > App Credentials > Client ID（基本信息 > 应用凭据 > 客户端 ID） | 与密钥配合，让工作区连接 Slack |
SLACK_OAUTH_CLIENT_SECRET | Client Secret（客户端密钥） | OAuth 客户端的另一半凭据 |
SLACK_SIGNING_SECRET | Signing Secret（签名密钥） | 验证 Slack 发来的每个请求。缺失时仍能发布通知和收件箱会话，但助手和按钮关闭，控制台显示 Slack 仅部分配置完成 |
请求 URL 和 OAuth 重定向基于每次安装都会设置的 API_PUBLIC_URL。如果第三方访问的 URL 与控制台使用的不同，可用 BACKEND_PUBLIC_URL 覆盖。
三个值都需要配置到后端和消费者，并在修改后重启。客户端密钥和签名密钥应与其他凭据同样保护：轮换时，在 Basic Information（基本信息） 中重新生成，更新 .env，然后重启。另见配置参考。
一个或多个工作区
自己的 Slack 工作区。 应用可以直接安装到创建它的 Slack 工作区，无需额外步骤。这是常见的自托管方式：你的团队使用自己的 Slack。
其他 Slack 工作区。 如果实例服务于多家公司，每家都有自己的 Slack，应用需要开启分发。在应用设置中打开 Manage Distribution（管理分发），完成检查清单，再选择 Activate Public Distribution（启用公开分发）。之后任何 Slack 工作区都可以通过集成 > Slack安装它。这不会将应用上架 Slack Marketplace，也无需向 Marketplace 提交。
Slack 限制 Marketplace 之外分发应用的历史读取
对于在 2025 年 5 月之后创建、商业分发且未进入 Slack Marketplace 的应用，Slack 对 conversations.history 和 conversations.replies 施加严格速率限制：本文编写时为每分钟一次请求，最多返回 15 条消息。仅安装在创建它们的工作区中的内部应用不受影响。参见 Slack 的公告。
Warmbly 仅在有人在线程中提及机器人，或使用就此询问 Warmbly时，才调用这些接口读取此前消息。Slack 限流时，助手会仅根据收到的那条消息作答，不包含周围线程上下文。其他功能不受影响。
助手面板
Slack 助手面板是从 Slack AI 应用入口打开的侧边面板，只有 Slack 工作区允许 AI 应用时才会出现。这由 Slack 工作区设置控制，并非所有 Slack 套餐都提供。如果未启用，面板不会显示，但私信、提及、消息快捷操作和收件箱频道仍正常工作。