> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Slack

將你的 Agent 加入 Slack，讓使用者能在共用頻道討論串或私訊中傳訊息給它。有人傳送訊息時，Mastra 會透過一般的 Agent pipeline 執行你的 Agent，並將回覆串流傳回 Slack。Slack adapter 會替你處理 Slack AI 指示器與互動式資訊卡。

## 安裝

從 Chat SDK 安裝 Slack adapter：

**npm**:

```bash
npm install @chat-adapter/slack
```

**pnpm**:

```bash
pnpm add @chat-adapter/slack
```

**Yarn**:

```bash
yarn add @chat-adapter/slack
```

**Bun**:

```bash
bun add @chat-adapter/slack
```

將 `createSlackAdapter()` 加入 Agent 的 `channels.adapters` 物件：

```typescript
import { Agent } from '@mastra/core/agent'
import { createSlackAdapter } from '@chat-adapter/slack'

export const yourAgent = new Agent({
  id: 'your-agent',
  name: 'Your Agent',
  instructions: 'Help people plan tasks, answer questions, and coordinate work in Slack.',
  model: 'anthropic/claude-opus-4-7',
  channels: {
    adapters: {
      slack: createSlackAdapter(),
    },
  },
})
```

## 建立 Slack app

若要連接你的 Agent，請在你想執行 Agent 的 Workspace 中建立 Slack app。Slack app 會控制 Agent 在 Slack 中的顯示方式、功能，以及它接收的事件。

本指南使用 [manifest](https://docs.slack.dev/app-manifests/configuring-apps-with-app-manifests/#creating_manifests)：這是一個會替你建立 Slack app 設定的設定檔。若要將 Agent 加入自己的 Workspace，這是最快的方法。本指南不涵蓋由其他 Workspace 安裝你的 Agent 時所使用的平台 OAuth 流程。

從 manifest 建立 Slack app：

1. 開啟 [api.slack.com/apps](https://api.slack.com/apps)。
2. 選取 **Create an app**。
3. 選取 **From a manifest**。
4. 選擇要執行 Agent 的 Workspace。
5. 貼上下列 manifest，然後選取 **Create**。Slack 接受 JSON 或 YAML，因此請使用 app 建立對話框中與下列格式相符的分頁：

**JSON**:

```json
{
  "display_information": {
    "name": "mastra-agent"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "mastra-agent",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "im:write",
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "users:read",
        "im:read",
        "im:history"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook",
      "bot_events": ["app_mention", "message.channels", "message.im"]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook"
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": false,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}
```

**YAML**:

```yaml
display_information:
  name: mastra-agent
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: mastra-agent
    always_online: true
oauth_config:
  scopes:
    bot:
      - im:write
      - app_mentions:read
      - channels:history
      - channels:read
      - chat:write
      - users:read
      - im:read
      - im:history
  pkce_enabled: false
settings:
  event_subscriptions:
    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
    bot_events:
      - app_mention
      - message.channels
      - message.im
  interactivity:
    is_enabled: true
    request_url: https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
  is_mcp_enabled: false
```

這份 manifest 會設定：

- `display_information.name` 與 `features.bot_user.display_name`：設定 Agent 在 Slack 中的名稱。你可以隨時更新。變更名稱或權限後，請記得重新安裝 app。
- `app_home.messages_tab_enabled` 與 `app_home.messages_tab_read_only_enabled`：啟用 Slack app **Messages** 分頁中的私訊功能。
- `always_online`：將 Slack bot 使用者顯示為隨時在線。
- `oauth_config.scopes.bot`：授予在 bot 所在頻道中發佈與讀取訊息的權限。這也包含提及、私訊與使用者查詢。
- `event_subscriptions`：告訴 Slack 要將哪些訊息事件傳送至 webhook。
- `interactivity`：啟用互動式資訊卡，並告訴 Slack 要將資訊卡操作傳送到哪裡。

建立 app 後，開啟 **Install App**、選取 **Install to Workspace**，並核准要求的 scopes。

## 設定 Slack 憑證

在 Mastra 中設定 Slack 憑證，讓它能驗證 Slack 請求並將訊息傳回 Slack。

在 Slack app 設定中複製下列值：

- **Basic Information** > **App Credentials** > **Signing Secret**
- **OAuth & Permissions** > **Bot User OAuth Token**

在 Mastra 環境中設定這些值：

```bash
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_TOKEN=xoxb-your-bot-token
```

Mastra 會自動讀取這些環境變數。

## 設定 webhook 路由

Slack 會透過 webhook 將頻道活動傳送至 Mastra。Webhook 是一個 HTTP endpoint；當新訊息、提及或使用者選取互動式資訊卡等事件發生時，Slack 便會呼叫它。

Mastra 會自動為你的 Agent 註冊 Slack webhook 路由：

```text
/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
```

使用公開的 Mastra server URL 與產生的路由組成 webhook URL：

```text
https://<YOUR-PUBLIC-URL>/api/agents/<YOUR-AGENT-ID>/channels/slack/webhook
```

Slack 無法將事件傳送至 `localhost`。在本機開發時，請讓 Mastra 開發伺服器持續執行，並先使用 tunnel 公開 `http://localhost:4111`，再於 Slack 中儲存 request URL。

本機開發可使用 `cloudflared` 或 `ngrok` 等 tunnel：

**npm**:

```bash
npx cloudflared tunnel --url http://localhost:4111
```

**pnpm**:

```bash
pnpm dlx cloudflared tunnel --url http://localhost:4111
```

**Yarn**:

```bash
yarn dlx cloudflared tunnel --url http://localhost:4111
```

**Bun**:

```bash
bun x cloudflared tunnel --url http://localhost:4111
```

使用產生的 tunnel host 作為 `<YOUR-PUBLIC-URL>`，例如：

```text
https://abc123.trycloudflare.com/api/agents/your-agent/channels/slack/webhook
```

更新 Slack 中的 request URL：

1. 在 Slack app 設定中開啟 **Event Subscriptions**。
2. 將 **Request URL** 替換為最終的 webhook URL。
3. 選取 **Save Changes**。
4. 開啟 **Interactivity & Shortcuts**。
5. 將 **Request URL** 替換為相同的 webhook URL。
6. 選取 **Save Changes**。
7. 如果 Slack 要求你重新安裝 app，請開啟 **OAuth & Permissions**，然後選取 **Reinstall to Workspace**。

## 在 Slack 中試用

開啟與 Slack bot 使用者的私訊並傳送訊息。私訊可以運作，是因為 manifest 包含 `message.im` 事件與 `im:*` scopes。

若要在頻道中使用 Agent，請先邀請 Slack bot 使用者：

```text
/invite @your-bot-name
```

在頻道中提及 bot：

```text
@your-bot-name What can you help me with?
```

Agent 會在討論串中回覆。回覆內容取決於 Agent 所設定的 model、instructions、memory 與 Tool。

## 驗證

Slack adapter 沒有內建使用者 allowlist。安裝 app 後，Workspace 中的任何人都可以透過私訊 Agent，或在 Agent 所在的頻道中提及它來與它互動。Slack 會使用 signing secret 驗證每個請求，而 Mastra 會針對 webhook 收到的每則有效訊息執行 Agent。

控制存取權的主要機制是頻道成員資格。Bot 只會收到私訊事件，以及來自已邀請它加入之頻道的事件，因此 bot 所屬的頻道集合決定了誰能使用它。不要將 bot 加入不應回覆的頻道；若要切斷存取權，請將它移出該頻道。

若需要更細緻的控制，請依傳送者身分設限。每個請求都會在 channel [request context](#request-context) 中攜帶傳送者的 Slack 使用者 ID，因此可以在 Agent 採取動作前，於 input processor 或 Tool 中允許或拒絕特定使用者。

### Server 驗證

Slack webhook 路由不受 Mastra [server 驗證](https://mastra.zisheng.pro/zh-TW/docs/server/auth)限制。Slack 無法傳送 bearer token，因此 Mastra 會將 channel webhook 註冊為公開路由，改以 Slack signing secret 驗證每個請求。即使啟用 [`MastraAuthSimple`](https://mastra.zisheng.pro/zh-TW/docs/server/auth/simple-auth) 等 Provider，情況也相同：API 的其餘部分仍受保護，但 webhook 路由依賴 signing secret，而非 server auth。請務必設定 `SLACK_SIGNING_SECRET`，讓 adapter 能拒絕並非由 Slack 簽署的請求。

### 外部頻道

共用頻道（[Slack Connect](https://slack.com/connect)）可讓其他 Workspace 的使用者加入對話。如果 Workspace 成員將 bot 加入共用頻道，該頻道中的每個人都能與 Agent 互動，包括組織外部的成員。任何能使用 Agent 的人，也能存取 Agent 可使用的 Tool 與資料。

將 bot 加入共用或外部頻道，應視同授予這些參與者 Agent 的存取權。執行前，請確認 Agent 的 Tool 與資料可以安全地開放給外部成員；若需要限制 Agent 回覆的對象，請依傳送者的使用者 ID 設限。

## Request context

每次收到訊息時，Mastra 都會在 [request context](https://mastra.zisheng.pro/zh-TW/docs/server/request-context) 的 `channel` key 下放置 channel context 物件。此物件包含傳送者的 Slack 顯示名稱與使用者 ID、bot 本身的身分，以及訊息來源的詳細資訊。從 input processor 或 Tool 中讀取它，即可識別使用者，或依對話類型採取不同處理方式：

```typescript
import { createTool } from '@mastra/core/tools'
import type { ChannelContext } from '@mastra/core/channels'
import { z } from 'zod'

export const whoami = createTool({
  id: 'whoami',
  description: 'Return the Slack identity of the current user',
  inputSchema: z.object({}),
  execute: async (_input, context) => {
    const channel = context?.requestContext?.get('channel') as ChannelContext | undefined

    return {
      platform: channel?.platform,
      userId: channel?.userId,
      userName: channel?.userName,
      isDM: channel?.isDM,
    }
  },
})
```

Channel context 包含：

- `botMention`、`botUserId` 與 `botUserName`：Bot 本身在 Slack 上的身分。
- `channelId` 與 `threadId`：訊息抵達的 Slack 頻道與討論串。
- `isDM`：訊息是否為私訊。
- `platform`：平台識別碼；此 adapter 的值為 `slack`。
- `userId` 與 `userName`：傳送者的 Slack 使用者 ID 與顯示名稱。

Mastra 也會將此 context 轉換成簡短的 system message。Agent 會得知平台及自身身分，以及對話是私訊還是公開頻道。若要瞭解如何變更此行為，請參閱 Channels 概觀中的[討論串 context](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)。

## 正式環境部署

部署 Mastra server 時，請將 Slack app 設定中的兩個 request URL 都更新為正式環境的 webhook URL。本機開發所使用的 tunnel URL 是暫時的，且會在 tunnel 重新啟動時變更。

Serverless 平台上的 Channels 可能需要 `waitUntil` 與共用的 pub/sub 設定，才能讓背景回覆與 thread lease 在短生命週期的 instance 之間正常運作。請參閱 Channels 概觀中的 [serverless 部署](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)。

### 閒置伺服器

平台伺服器在未收到流量時會縮減至閒置狀態，而這對 Slack 不成問題。下一個事件（例如提及或私訊）會透過傳遞 webhook 請求喚醒伺服器，接著伺服器便會繼續處理請求。伺服器閒置後的第一次回覆可能因啟動而稍久一些，這是預期行為。Slack 預期在 3 秒內收到 `200` 確認；若傳遞失敗或逾時，最多會重試事件三次。因此，若冷啟動非常緩慢，Agent 可能要等到重試後才會回覆。只要伺服器保持 warm，後續訊息就會以正常速度獲得回覆。

## 相關內容

- [Channels 概觀](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)
- [其他內容](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/other-adapters)
- [Channels 參考資料](https://mastra.zisheng.pro/zh-TW/reference/agents/channels)
- [部署概觀](https://mastra.zisheng.pro/zh-TW/docs/deployment/overview)