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

# ChannelProvider

`ChannelProvider` 是平台整合用來將 Agent 連接至訊息平台的介面。Provider 擁有整項整合的完整生命週期：app 佈建與 OAuth、webhook 路由與事件處理、adapter 建立與 Agent 接線，以及認證管理。

在 `Mastra` 建構函式的 `channels` 下註冊 Provider，並以你選擇的 ID 作為 key。每個 Provider 的 route 都會自動合併至伺服器的 API route，且 `initialize()` 會在 Mastra 啟動期間執行。

```typescript
import { Mastra } from '@mastra/core/mastra'
import { SlackProvider } from '@mastra/slack'

export const mastra = new Mastra({
  channels: {
    slack: new SlackProvider({
      refreshToken: process.env.SLACK_REFRESH_TOKEN!,
      baseUrl: process.env.MASTRA_BASE_URL,
    }),
  },
})
```

Provider 的 `baseUrl` 是平台傳送 webhook 與事件的公開 URL。在正式環境中，這就是已部署 Mastra 伺服器的 URL。本機開發時，平台無法連線至 `http://localhost:4111`，因此請執行 tunnel（例如 [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) 或 [ngrok](https://ngrok.com/)），並將 `baseUrl` 指向 tunnel URL（例如 `https://abc123.trycloudflare.com`），讓事件送達本機開發處理程序。

[`SlackProvider`](https://mastra.zisheng.pro/zh-TW/reference/channels/slack-provider) 是第一個內建實作。實作此介面即可建立自訂 Provider。

## 屬性

**id** (`string`): 此 channel 類型的唯一識別碼，例如 'slack' 或 'discord'。路由事件及從 Mastra 查找 Provider 時，會使用此值作為 key。

## 方法

**getRoutes** (`() => ApiRoute[]`): 傳回此 channel 的 API route（OAuth、webhook、事件）。這些 route 會自動合併至伺服器的 apiRoutes。

**initialize** (`() => Promise<void>`): 所有 Agent 註冊完成後，在 Mastra 初始化期間呼叫。可用於還原作用中 installation 等非同步設定工作，但不會佈建新的 app。

**configure** (`(credentials: Record<string, unknown> | null) => void | Promise<void>`): 在執行階段提供或清除平台認證。傳入 null 可清除認證並刪除已儲存的 token。

**getInfo** (`() => ChannelPlatformInfo`): 傳回 editor UI 的探索中繼資料：平台名稱、設定狀態與 connect 選項 schema。

**connect** (`(agentId: string, options?: Record<string, unknown>) => Promise<ChannelConnectResult>`): 將 Agent 連接至平台。傳回 discriminated result，說明完成連線所需的授權流程。

**disconnect** (`(agentId: string) => Promise<void>`): 中斷 Agent 與平台的連線。刪除平台 app 並清除已儲存的狀態。

**listInstallations** (`() => Promise<ChannelInstallationInfo[]>`): 列出此平台作用中的 installation。只傳回公開資訊，絕不傳回 secret。

## 存取 Provider

透過 `channels` getter 存取已註冊的 Provider，並以註冊時使用的 ID 作為 key。getter 的型別來自建構函式設定，因此 `mastra.channels.slack` 是具有完整方法介面的具體 Provider。

```typescript
await mastra.channels.slack.configure({ refreshToken })
```

若只在執行階段才知道 key，請改用字串 ID 查找 Provider。`getChannelProvider` 接受具體型別作為泛型，而 `getChannelProviders` 會傳回以 ID 為 key 的所有已註冊 Provider。

```typescript
import type { SlackProvider } from '@mastra/slack'

const slack = mastra.getChannelProvider<SlackProvider>('slack')
const all = mastra.getChannelProviders()
```

## 相關內容

- [SlackProvider](https://mastra.zisheng.pro/zh-TW/reference/channels/slack-provider)
- [Channels](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)