Slack

概览

Slack provider 将你的数字员工集成到 Slack 工作区中。它支持：

• 私信（DM）
• 频道消息
• App 提及
• 交互组件（按钮、菜单）
• Block Kit 富消息
• Slash commands
• 线程回复

前置条件

• 一个 Slack 工作区
• 用于创建 Slack app 的管理员权限

设置

1. 创建 Slack 配置令牌对

   前往 api.slack.com/apps 并创建 app configuration token pair。复制两个值：

   • Configuration access token (xoxe.xoxp-...)
   • Configuration refresh token (xoxe-1-...)

2. 配置 provider

   answers.json

   {
     "setup_answers": {
       "messaging-slack": {
         "slack_configuration_access_token": "xoxe.xoxp-xxx",
         "slack_configuration_refresh_token": "xoxe-1-xxx"
       }
     }
   }

3. 运行 setup

   gtc setup --answers answers.json ./my-bundle

4. 点击 Add to Slack

   setup 会注册或更新 Slack app，并显示 Add to Slack 操作。打开生成的 Slack authorization URL，选择 workspace，检查请求的 scopes，然后批准安装。

   当 OAuth redirect 返回 setup 时，Greentic 会为 tenant 保存 Slack app id、client id、client secret 和 runtime OAuth answers。如果 callback 未自动处理，请在批准安装后再次运行 gtc setup --answers answers.json ./my-bundle。

5. 在 Slack 中添加 app

   打开 Slack，确认 app 已安装到 workspace。对于频道对话，请将 app 添加到 worker 应响应的 channel。你可以在 channel 的 integration settings 中添加，也可以在 channel 中 mention/invite 该 app。

6. 启动或重启 runtime

   gtc start ./my-bundle

   启动时会使用已保存的 slack_app_id 和配置令牌对，用当前 webhook URL 更新 Slack app manifest。

7. 测试频道

   向 app 发送 direct message，或在已添加该 app 的 Slack channel 中 mention 它。channel events 只会到达 app 是成员且已安装 scopes 允许该 event 的 channel。

配置选项

选项	必需	描述
slack_configuration_access_token	是	用于 app manifest 更新的短期 Slack configuration token
slack_configuration_refresh_token	是	用于轮换 configuration access token 的 refresh token
slack_app_id	已生成	setup 创建或返回的 Slack app id
slack_client_id	已生成	app registration 返回的 Slack OAuth client id
client_secret	生成的 secret	app registration 返回的 Slack OAuth client secret

注意

新的 setup flows 不需要手动输入 slack_bot_token。setup action 和 OAuth install flow 会保存 runtime credentials。如果你正在升级旧 bundle，请使用 gtc setup --dry-run --emit-answers answers.json ./my-bundle 重新生成 answers，然后重新运行 setup。

警告

Slack configuration access tokens 会过期。请将匹配的 refresh token 保存在 setup secrets store 中，以便 provider 在 manifest 更新期间轮换这对令牌。

功能

文本消息

- id: reply
  type: reply
  config:
    message: "Hello! How can I help you?"

Markdown 格式

Slack 使用 mrkdwn 格式：

- id: formatted
  type: reply
  config:
    message: |
      *Bold* _Italic_ `code`
      >Blockquote
      • Bullet point

Block Kit 消息

使用 Slack 的 Block Kit 构建丰富布局：

- id: rich_message
  type: reply
  config:
    blocks:
      - type: section
        text:
          type: mrkdwn
          text: "*Welcome!*\nHow can I assist you today?"
      - type: divider
      - type: actions
        elements:
          - type: button
            text:
              type: plain_text
              text: "Get Help"
            action_id: "help_clicked"
            value: "help"
          - type: button
            text:
              type: plain_text
              text: "View Status"
            action_id: "status_clicked"
            value: "status"

交互按钮

- id: ask_action
  type: reply
  config:
    message: "What would you like to do?"
    blocks:
      - type: actions
        elements:
          - type: button
            text:
              type: plain_text
              text: "Create Ticket"
            style: primary
            action_id: "create_ticket"
          - type: button
            text:
              type: plain_text
              text: "Cancel"
            style: danger
            action_id: "cancel"

选择菜单

- id: select_option
  type: reply
  config:
    blocks:
      - type: section
        text:
          type: mrkdwn
          text: "Select a category:"
        accessory:
          type: static_select
          action_id: "category_select"
          options:
            - text:
                type: plain_text
                text: "Technical Support"
              value: "technical"
            - text:
                type: plain_text
                text: "Billing"
              value: "billing"
            - text:
                type: plain_text
                text: "General"
              value: "general"

线程回复

在线程中回复：

- id: thread_reply
  type: reply
  config:
    message: "This replies in the thread"
    thread_ts: "{{original_message.thread_ts}}"

文件上传

Slack 的文件 API 会随时间变化。仅当已安装的 messaging-slack pack 为您的版本公开文件支持时才使用此功能；否则请发送链接，或使用 Slack 当前的外部上传流程。

- id: upload_file
  type: reply
  config:
    files:
      - url: "https://example.com/report.pdf"
        filename: "report.pdf"
        title: "Monthly Report"

临时消息

仅对单个用户可见的消息：

- id: ephemeral
  type: reply
  config:
    message: "Only you can see this"
    ephemeral: true
    user: "{{user_id}}"

处理交互

按钮点击

flows/on_interaction.ygtc

name: handle_interaction
version: "1.0"

nodes:
  - id: route_action
    type: branch
    config:
      conditions:
        - expression: "action_id == 'help_clicked'"
          to: show_help
        - expression: "action_id == 'create_ticket'"
          to: create_ticket
      default: unknown_action

  - id: show_help
    type: reply
    config:
      message: "Here's how I can help..."

triggers:
  - type: block_action
    target: route_action

选择菜单变更

- id: handle_select
  type: branch
  config:
    conditions:
      - expression: "selected_value == 'technical'"
        to: technical_flow
      - expression: "selected_value == 'billing'"
        to: billing_flow

Slash Commands

注意

Slash commands 需要在 Slack 中额外进行 app 配置。

1. 前往 app 设置中的 Slash Commands
2. 创建一个命令（例如 /support）
3. 将 Request URL 设置为你的 webhook

在 flow 中处理：

flows/slash_command.ygtc

name: slash_command
version: "1.0"

nodes:
  - id: handle_command
    type: reply
    config:
      message: "Support bot at your service!"
      response_type: in_channel  # or "ephemeral"

triggers:
  - type: slash_command
    command: "/support"
    target: handle_command

频道配置

单个频道

greentic.demo.yaml

tenants:
  demo:
    teams:
      support:
        channels:
          slack:
            provider: messaging-slack
            config:
              channel_id: "C1234567890"

多个频道

tenants:
  demo:
    teams:
      support:
        channels:
          slack-general:
            provider: messaging-slack
            config:
              channel_id: "C1234567890"
          slack-vip:
            provider: messaging-slack
            config:
              channel_id: "C0987654321"

故障排查

App 未接收消息

1. 验证 Event Subscriptions：

   • 检查 Request URL 是否正确
   • 确认 events 已启用
   • 确认 bot 已订阅正确的 events

2. 检查 Bot 权限：

   • 添加 scopes 后重新安装 app
   • 确认 bot 已加入频道

3. 测试 Webhook：

   curl https://your-domain.com/v1/messaging/ingress/messaging-slack/demo/default

not_authed 错误

你的 bot token 无效或已过期。请从 OAuth & Permissions 获取新的 token。

channel_not_found 错误

• 确认 channel ID 正确
• 确认 bot 已被加入频道
• 检查频道是否已归档

速率限制

Slack 的速率限制因 method 而异。请优雅处理：

- id: reply
  type: reply
  config:
    message: "Response"
    retry_on_rate_limit: true
    max_retries: 3

安全

警告

校验 Slack 请求签名，以防止未授权请求。

Greentic 会自动校验：

• 请求时间戳
• 使用 signing secret 的签名
• Token 校验

下一步

• Block Kit Builder - 设计富消息
• Teams Provider - 添加 Teams 集成