SlackProvider

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

使用例

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

src/mastra/index.ts

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() を呼び出します。

src/mastra/index.ts

const slack = new SlackProvider()

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

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

SlackProviderConfig は、Slack 固有のフィールド、Slack Adapter のオーバーライド（toolDisplay、streaming、typingStatus）、接続されたすべての Agent に転送される ChannelConfig オプションの一部（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 完了後のリダイレクト先パス。

onInstall?:

(installation: SlackInstallation) => Promise<void>

Workspace にアプリが正常にインストールされたときに呼び出されます。

streaming?:

StreamingConfig | false

= true

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

textFormat?:

'markdown' | 'plain'

= 'markdown'

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

toolDisplay?:

ToolDisplay

= 'grouped'

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

typingStatus?:

boolean | TypingStatusFn

= true

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

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 を返します。

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

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

戻り値：Promise<ChannelConnectResult>

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 から切断します。

await slack.disconnect('support-agent')

戻り値：Promise<void>

getInstallation(agentId)

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

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

戻り値：Promise<SlackInstallation | null>

listInstallations()

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

const installations = await slack.listInstallations()

戻り値：Promise<ChannelInstallationInfo[]>

設定

configure(credentials)

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

// 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 が不明で、サーバー設定からも自動検出できない場合に使用してください。

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

initialize()

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

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 にアクセスします。

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

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

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

ストレージ要件

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

関連情報

• ChannelProvider：SlackProvider が実装するインターフェース
• Channels：概念、プラットフォームの設定、createSlackAdapter を使用する方法
• Channels リファレンス：Agent コンストラクターの channels 設定