Slack

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

安裝

從 Chat SDK 安裝 Slack adapter：

npm

npm install @chat-adapter/slack

pnpm

pnpm add @chat-adapter/slack

Yarn

yarn add @chat-adapter/slack

Bun

bun add @chat-adapter/slack

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

src/mastra/agents/your-agent.ts

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：這是一個會替你建立 Slack app 設定的設定檔。若要將 Agent 加入自己的 Workspace，這是最快的方法。本指南不涵蓋由其他 Workspace 安裝你的 Agent 時所使用的平台 OAuth 流程。

從 manifest 建立 Slack app：

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

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

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 環境中設定這些值：

.env

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 路由：

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

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

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

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

pnpm

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

Yarn

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

Bun

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

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

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 使用者：

/invite @your-bot-name

在頻道中提及 bot：

@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 中攜帶傳送者的 Slack 使用者 ID，因此可以在 Agent 採取動作前，於 input processor 或 Tool 中允許或拒絕特定使用者。

Server 驗證

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

外部頻道

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

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

Request context

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

src/mastra/tools/whoami.ts

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。

正式環境部署

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

Serverless 平台上的 Channels 可能需要 waitUntil 與共用的 pub/sub 設定，才能讓背景回覆與 thread lease 在短生命週期的 instance 之間正常運作。請參閱 Channels 概觀中的 serverless 部署。

閒置伺服器

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

相關內容

• Channels 概觀
• 其他內容
• Channels 參考資料
• 部署概觀