# 接入 Slack 机器人

创建 Slack 应用并连接数据智能体，让团队在频道或私聊中问数，查看消息的处理和投递结果。

把数据智能体接到 Slack 后，团队可以在频道里 `@` 机器人，或通过私聊直接提问，答案会返回 Slack。接入使用 [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode/)，不需要暴露公网回调地址。

## 开始前

- 有权在 Slack 工作区创建并安装应用；如果企业限制安装，需要工作区管理员批准。
- 已有配好数据源和技能的[数据智能体](https://docs.asktable.com/agent/overview)，当前 AskTable 项目角色是项目负责人或项目管理员。
- 一个 AskTable 项目应只接入一个 Slack 工作区，避免人员身份匹配冲突。
- 私有部署需要运行支持 Slack 的[频道网关](https://docs.asktable.com/deploy/feishu-gateway)。

一个智能体可以保存飞书和 Slack 两套配置，但同时只启用一个平台。切换或选择「不启用」会保留配置，之后可以切回。

## 1. 创建 Slack 应用

打开 [Slack apps](https://api.slack.com/apps)，选择 **Create New App → From an app manifest**，选定工作区后粘贴以下 YAML：

```yaml
_metadata:
  major_version: 1
display_information:
  name: AskTable
  description: Ask questions about your data in natural language
features:
  bot_user:
    display_name: AskTable
    always_online: true
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - im:history
      - chat:write
      - reactions:write
      - users:read
      - users:read.email
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  socket_mode_enabled: true
  org_deploy_enabled: false
  token_rotation_enabled: false
```

检查设置后点 **Create**。应用名称和机器人显示名可以按团队需要修改。

| 权限用途    | 对应设置                                            |
| ------- | ----------------------------------------------- |
| 收到问题    | `app_mentions:read` 接收提及，`im:history` 接收私聊      |
| 回答与接收确认 | `chat:write` 发送回答，`reactions:write` 添加确认表情      |
| 匹配人员    | `users:read`、`users:read.email` 获取姓名、头像、邮箱等人员资料 |

保留 Messages 页签的启用设置，并允许在其中发消息，否则用户无法私聊机器人。清单不申请 `channels:history` 或 `groups:history`，机器人不会读取无关的频道聊天，因此频道和话题里的每次提问都要 `@`。

## 2. 获取两个 Token

在 **OAuth & Permissions** 中点 **Install to Workspace** 并批准权限，复制以 `xoxb-` 开头的 **Bot User OAuth Token**。

然后进入 **Basic Information → App-Level Tokens**：

1. 点 **Generate Token and Scopes** 并填写名称。
2. 添加 `connections:write` 权限。
3. 生成并复制以 `xapp-` 开头的 Token。

| AskTable 字段 | 填什么                                                   |
| ----------- | ----------------------------------------------------- |
| Bot Token   | `xoxb-` 开头的 Bot User OAuth Token，用于调用 Slack API 和发送回答 |
| App Token   | `xapp-` 开头的 App-Level Token，用于建立 Socket Mode 连接       |

无需 Signing Secret。两个 Token 都是凭据，不要放进截图或代码仓库；泄露后应在 Slack 撤销并生成替代值。

## 3. 在 AskTable 启用 Slack

左侧主导航 →「更多」→ 打开目标智能体 →「频道」：

1. 在「平台」中选择 **Slack**。
2. 首次配置时，在弹窗中填入 Bot Token 和 App Token，点「保存」。
3. 保存成功后 Slack 才生效；取消弹窗会保留原平台选择。

表单会检查两个 Token 的前缀。以后选择已经配置的 Slack 会直接启用，修改凭据用「凭证配置」旁的「修改配置」；编辑时会回填已有凭证，只需替换要更新的值，两个 Token 都不能清空。

「通用配置」可以调整回答方式：

| 设置     | 默认值          | 用途                     |
| ------ | ------------ | ---------------------- |
| 在话题中回复 | 开启           | 对频道里的新提问开话题回复，让追问集中在一起 |
| 深度推理   | 关闭           | 给复杂问题更多推理时间            |
| 渠道偏好   | 空，最多 1024 字符 | 为每轮分析补充常驻要求，例如“先给结论”   |

开关即时保存，渠道偏好失焦保存。深度推理和偏好从下一条消息生效。私聊始终直接回复，不另开话题。

### 控制谁可以问数

启用后，下方「人员权限」可打开白名单。Slack 默认关闭白名单，能联系机器人的用户都可提问。打开后，需要把 Slack 用户身份关联到 AskTable 人员，并授予其使用该智能体的权限；按角色限定数据范围的方法见[权限与数据范围](https://docs.asktable.com/permissions)。未建立绑定或未获得授权的用户会被拒绝并进入待审批。

飞书和 Slack 的白名单开关各自保存，切换平台后应检查当前平台的设置。

## 4. 检查连接和消息

| 连接状态 | 含义                        |
| ---- | ------------------------- |
| 已连接  | 当前 Slack Socket Mode 连接正常 |
| 连接中  | 正在建立或恢复连接                 |
| 未连接  | 当前没有可用连接                  |
| 错误   | 建连或运行发生错误，查看状态旁的说明        |

状态每 5 秒自动刷新；「刷新」只重新读取状态，不会手动重建连接。已连接或网关心跳正常不能证明一次提问已成功回答。

发送测试问题后，看「最近消息」是否更新，再点「详情」检查**处理状态**和**回复状态**。处理失败说明问题出在分析等处理环节，回复失败则说明结果未成功投递到 Slack。

## 5. 邀请机器人并提问

在目标频道里输入以下命令，名称换成你的机器人名称：

```text
/invite @AskTable
```

也可以从频道设置的 **Integrations → Add apps** 添加。私聊无需邀请。

| 位置    | 示例                      |
| ----- | ----------------------- |
| 私聊    | `上个月的销售额是多少？`           |
| 频道    | `@AskTable 上个月的销售额是多少？` |
| 话题内追问 | `@AskTable 按地区拆分。`      |

话题内的追问也必须 `@`。一个话题的分析上下文属于最初提问者，其他人应在频道另发一条问题。多人私聊不受支持。

私聊和频道顶层问答按同一人复用会话，连续 24 小时没有新消息后重新开始；话题会话不按这个窗口过期。频道或话题内的回答对能查看该位置的成员可见，需要私下查看的结果请使用私聊。

## 出问题怎么判断

| 现象                | 检查与处理                                                                      |
| ----------------- | -------------------------------------------------------------------------- |
| 显示错误              | 确认两个 Token 的前缀正确、Socket Mode 已开启、App Token 有 `connections:write`，应用已安装到工作区 |
| 最近消息没有变化          | 确认机器人已加入频道、问题带 `@`、已订阅 `app_mention` 和 `message.im`；私聊还需启用 Messages 页签     |
| 处理失败              | 点「详情」看原因，检查数据源和人员授权，再重试问题                                                  |
| 回复失败              | 确认机器人仍在频道、有 `chat:write`；修改 Slack 权限后重新安装应用到工作区                            |
| 提示没有权限或进入待审批      | 关联正确的 Slack 人员身份，并授予其当前智能体的访问权限                                            |
| 切换平台后收不到 Slack 消息 | 确认当前「平台」仍为 Slack；切到飞书或不启用时，Slack 配置保留但不接收消息                                |

## 下一步

- 维护智能体的数据和分析方法：[智能体概览](https://docs.asktable.com/agent/overview)
- 限定各人的数据范围：[权限与数据范围](https://docs.asktable.com/permissions)
- 连接另一个支持的平台：[接入飞书机器人](https://docs.asktable.com/integrations/feishu)