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

# SlackProvider

`SlackProvider` は、Agent を Slack に接続するためのマネージドな手段です。`Mastra.channels` に登録すると、Manifest API を通じた Slack アプリのプロビジョニング、OAuth インストールフローの実行、設定トークンのローテーション、Slack イベントの Agent へのルーティングが行われます。アプリの作成とインストールを Mastra に管理させる場合に使用します。Slack アプリを自分で作成し、スコープと Webhook を設定する低レベルの手段については、Agent の `channels.adapters` で [`createSlackAdapter`](https://mastra.zisheng.pro/ja/docs/capabilities/channels/slack) を使用してください。

## 使用例

Provider を `Mastra` コンストラクターに登録します。Refresh token は1回限り使用でき、起動時にローテーションされます。生成された Access token は `Mastra.storage` に永続化されます。

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

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

構築時に認証情報を使用できない場合（たとえば、Editor UI から入力する場合や Vault から読み込む場合）は、認証情報なしで Provider を構築し、後から [`configure()`](#configurecredentials) を呼び出します。

```typescript
const slack = new SlackProvider()

await slack.configure({
  refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
})
```

## コンストラクターパラメーター

`SlackProviderConfig` は、Slack 固有のフィールド、Slack Adapter のオーバーライド（`toolDisplay`、`streaming`、`typingStatus`）、接続されたすべての Agent に転送される [`ChannelConfig`](https://mastra.zisheng.pro/ja/reference/agents/channels) オプションの一部（`handlers`、`inlineMedia`、`state` など）を組み合わせたものです。すべてのフィールドは省略可能です。

**refreshToken** (`string`): Slack App Configuration の Refresh token。トークンの自動ローテーションに使用します。1回限り使用でき、ローテーションのたびに新しいペアが返されます。後から configure() で指定することもできます。省略すると、Provider は未設定の状態で起動し、configure() が呼び出されるかストレージからトークンが読み込まれるまでアプリを作成できません。api.slack.com/apps の「Your App Configuration Tokens」で生成してください。

**token** (`string`): プログラムによるアプリ作成に使用する Slack App Configuration の Access token。Provider は起動時に refreshToken を使用して新しいトークンにローテーションするため、省略可能です。

**baseUrl** (`string`): Webhook と OAuth コールバックの公開ベース URL。connect() を呼び出してアプリを作成する場合は必須です。setBaseUrl() で設定することも、Mastra サーバーの設定から自動検出することもできます。ローカル開発では、cloudflared などのトンネルを使用してください。

**encryptionKey** (`string`): 保存される機密データ（Client secret、Signing secret、Bot token）の暗号化キー。32文字以上のランダムな文字列を使用してください。MASTRA\_ENCRYPTION\_KEY 環境変数でも設定できます。省略すると、シークレットはプレーンテキストで保存されます（本番環境では非推奨）。

**storage** (`ChannelsStorage`): インストール用のカスタムストレージ。デフォルトでは、グローバルストレージの Mastra ChannelsStorage が使用されます。永続ストレージを利用できない場合はエラーをスローします。

**redirectPath** (`string`): OAuth 完了後のリダイレクト先パス。 (Default: `"/"`)

**onInstall** (`(installation: SlackInstallation) => Promise<void>`): Workspace にアプリが正常にインストールされたときに呼び出されます。

**streaming** (`StreamingConfig | false`): 生成された Agent のテキスト差分を Slack に Stream します。投稿と編集の間隔をカスタマイズするには { updateIntervalMs } を渡し、ステップ完了までテキストをバッファリングするには false を渡します。Streaming を無効にすると、toolDisplay は静的モードに制限されます。 (Default: `true`)

**textFormat** (`'markdown' | 'plain'`): Slack Adapter に転送する、Agent の最終応答テキストの形式。'markdown'（デフォルト）では応答を Markdown として投稿するため、Slack が太字、リンク、表をネイティブにレンダリングします。'plain' はリテラルなプレーンテキストを投稿するもので、Slack mrkdwn を出力するよう指示された Agent のための回避手段です。バッファリングされた応答（streaming: false）と Streaming のフォールバックに適用されます。ネイティブ Streaming は常に Markdown です。 (Default: `'markdown'`)

**toolDisplay** (`ToolDisplay`): Slack で Tool 呼び出しをレンダリングする方法：'cards'、'text'、'timeline'、'grouped'、'hidden'、または関数。'hidden' は Tool の呼び出しと結果のレンダリングを完全に抑止します。'timeline' と 'grouped' には Streaming が必要です。streaming: false の場合は静的モードのみ使用でき、デフォルトは 'cards' です。 (Default: `'grouped'`)

**typingStatus** (`boolean | TypingStatusFn`): Agent の処理中に入力インジケーターを表示します。無効にするには false を設定し、Stream チャンクごとにカスタムステータステキストを返すには関数を渡します（undefined を返すと、そのチャンクではデフォルトにフォールバックします）。 (Default: `true`)

**waitUntil** (`WaitUntilFn`): 現在の Slack Webhook リクエストに使用する waitUntil を返します。Hono がプラットフォームの ExecutionContext を橋渡しできないサーバーレスランタイム（Vercel、AWS Lambda）では必須です。指定しない場合、200 の応答確認後に呼び出しが停止し、実行が途中で終了します。プラットフォーム SDK（例：@vercel/functions）の waitUntil(promise) をそのまま渡してください。通常、Cloudflare Workers と Netlify では不要です。

**resolveWaitUntil** (`WaitUntilResolver`): ランタイムがリクエストを通じて waitUntil を公開しており、Core のデフォルトでは対応できない場合に、リクエストの Hono Context から waitUntil を解決します。解決順序：waitUntil → resolveWaitUntil → Core のデフォルト。

**handlers** (`ChannelHandlers`): 組み込みのイベントハンドラー（onDirectMessage、onMention）をオーバーライドします。この Provider を介して接続されたすべての Agent の AgentChannels に転送されます。

**inlineMedia** (`ChannelConfig['inlineMedia']`): モデルにインラインで送信するメディアタイプ。

**inlineLinks** (`ChannelConfig['inlineLinks']`): メッセージテキスト内の URL をファイルパーツに変換します。

**threadContext** (`ChannelConfig['threadContext']`): Agent が会話の途中から参加したときに、Slack から直近の Thread メッセージを取得します。

**tools** (`ChannelConfig['tools']`): Channel が AgentChannels.getTools() を介して Channel Tool（add\_reaction、remove\_reaction）を公開するかどうか。これらの Tool が Agent に自動で追加されることはありません。使用するには、tools: { ...channels.getTools() } を介して明示的に渡してください。

**state** (`ChannelConfig['state']`): メッセージの重複排除、ロック、サブスクリプションに使用する State Adapter。デフォルトでは、Mastra インスタンスに設定されたストレージを基盤とする MastraStateAdapter が使用されるため、サブスクリプションは再起動後も永続化されます。

**chatOptions** (`ChannelConfig['chatOptions']`): Chat SDK に直接渡す追加オプション。

**logger** (`SlackAdapterConfig['logger']`): 基盤となる SlackAdapter に転送する Logger。デフォルトでは Adapter の ConsoleLogger が使用されます。

## メソッド

### Agent の接続

#### `connect(agentId, options?)`

Manifest API を介して Agent 用の新しい Slack アプリを作成し、ユーザーのリダイレクト先となる認可 URL を含む OAuth の結果を返します。`baseUrl` の設定が必要です。Agent に保留中のインストールがすでに存在する場合は、重複するアプリを作成せず、既存の認可 URL を返します。

```typescript
const result = await slack.connect('support-agent', {
  name: 'Support Bot',
})

// Redirect the user to result.authorizationUrl to install the app
```

戻り値：`Promise<ChannelConnectResult>`

```typescript
interface ChannelConnectResult {
  type: 'oauth'
  installationId: string
  authorizationUrl: string
}
```

`SlackConnectOptions` はシリアライズ可能で、保存済み Agent 用に格納できます。

**name** (`string`): Slack Bot の表示名。デフォルトでは Agent 名、次に Agent ID が使用されます。

**description** (`string`): Slack に表示する Bot の説明。デフォルトは「{name} - Powered by Mastra」です。

**iconUrl** (`string`): アプリアイコン用の正方形画像（最小 512x512）の URL。自動的にダウンロードされ、Slack にアップロードされます。

**manifest** (`(defaults: SlackAppManifest) => SlackAppManifest`): Manifest API に送信する前に Slack アプリの Manifest をカスタマイズします。デフォルトの Manifest を受け取り、最終的な Manifest を返します。カスタムスコープ、追加イベント、インタラクティビティ設定に使用します。

**redirectUrl** (`string`): OAuth が正常に完了した後のリダイレクト先 URL。デフォルトでは Provider の redirectPath または / が使用されます。

#### `disconnect(agentId)`

Slack アプリを削除し、ストレージからインストールを削除して、Agent を Slack から切断します。

```typescript
await slack.disconnect('support-agent')
```

戻り値：`Promise<void>`

#### `getInstallation(agentId)`

Agent の Slack インストールを返します。存在しない場合は `null` を返します。

```typescript
const installation = await slack.getInstallation('support-agent')
```

戻り値：`Promise<SlackInstallation | null>`

#### `listInstallations()`

アクティブなものと保留中のものを含め、すべての Slack インストール（公開情報のみ）を一覧表示します。

```typescript
const installations = await slack.listInstallations()
```

戻り値：`Promise<ChannelInstallationInfo[]>`

### 設定

#### `configure(credentials)`

実行時に Slack App Configuration の認証情報を設定または消去します。構築時に認証情報を使用できない場合に使用してください。認証情報を消去して保存済みトークンを削除するには `null` を渡します。

```typescript
// Provide credentials (persists to storage immediately)
await slack.configure({ refreshToken: 'xoxe-1-...' })

// Clear credentials and stored tokens
await slack.configure(null)
```

戻り値：`Promise<void>`

#### `setBaseUrl(baseUrl)`

Webhook と OAuth コールバックに使用する公開ベース URL を設定します。構築時に URL が不明で、サーバー設定からも自動検出できない場合に使用してください。

```typescript
slack.setBaseUrl('https://abc123.trycloudflare.com')
```

#### `initialize()`

ストレージ内のアクティブなインストールごとに `SlackAdapter` を再作成し、対応する Agent に `AgentChannels` を注入して、起動時から Slack イベントを受信できるようにします。新しいアプリは自動でプロビジョニングしません。作成するには `connect()` を使用します。Mastra が自動的に呼び出すため、通常は直接呼び出す必要はありません。

```typescript
await slack.initialize()
```

戻り値：`Promise<void>`

## デフォルトの Manifest

`connect()` が Slack アプリを構築すると、生成される Manifest はデフォルトの Bot スコープとイベントサブスクリプションをリクエストします。オーバーライドするには、`connect()` の `manifest` オプションを使用します。

| デフォルトの Bot スコープ     | デフォルトの Bot イベント    |
| ------------------- | ------------------ |
| `chat:write`        | `app_mention`      |
| `chat:write.public` | `message.channels` |
| `im:write`          | `message.groups`   |
| `channels:history`  | `message.im`       |
| `channels:read`     | `message.mpim`     |
| `groups:history`    |                    |
| `groups:read`       |                    |
| `im:history`        |                    |
| `im:read`           |                    |
| `mpim:history`      |                    |
| `mpim:read`         |                    |
| `app_mentions:read` |                    |
| `users:read`        |                    |
| `reactions:write`   |                    |
| `files:read`        |                    |
| `assistant:write`   |                    |

## Provider へのアクセス

登録時に使用した ID をキーとして、型付けされた `channels` ゲッターから登録済み Provider にアクセスします。

```typescript
const result = await mastra.channels.slack.connect('support-agent')
```

キーが実行時にしか分からない場合は、文字列 ID で検索し、具象型を渡します。

```typescript
const slack = mastra.getChannelProvider<SlackProvider>('slack')
const result = await slack.connect('support-agent')
```

## ストレージ要件

`SlackProvider` でインストールとローテーションする設定トークンを暗号化して永続化するには、`Mastra` に永続ストレージが必要です。永続ストレージを利用できず、カスタム `storage` も渡されていない場合、コンストラクターはエラーをスローします。

## 関連情報

- [ChannelProvider](https://mastra.zisheng.pro/ja/reference/channels/channel-provider)：`SlackProvider` が実装するインターフェース
- [Channels](https://mastra.zisheng.pro/ja/docs/capabilities/channels/overview)：概念、プラットフォームの設定、`createSlackAdapter` を使用する方法
- [Channels リファレンス](https://mastra.zisheng.pro/ja/reference/agents/channels)：`Agent` コンストラクターの `channels` 設定