Skip to main content

ChannelProvider

ChannelProvider is the interface that platform integrations implement to connect agents to a messaging platform. A provider owns the full lifecycle of an integration: app provisioning and OAuth, webhook routing and event handling, adapter creation and agent wiring, and credential management.

Register providers on the Mastra constructor under channels, keyed by an id you choose. Each provider's routes are merged into the server's API routes automatically, and initialize() runs during Mastra startup.

src/mastra/index.ts
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,
    }),
  },
})

The provider's baseUrl is the public URL the platform sends webhooks and events to. In production this is your deployed Mastra server URL. For local development, the platform can't reach http://localhost:4111, so run a tunnel (such as cloudflared or ngrok) and point baseUrl at the tunnel URL (for example https://abc123.trycloudflare.com) so events reach your local dev process.

SlackProvider is the first built-in implementation. Build a custom provider by implementing this interface.

Properties
Direct link to Properties

id:

string
Unique identifier for this channel type, for example 'slack' or 'discord'. Used as the key when routing events and looking the provider up from Mastra.

Methods
Direct link to Methods

getRoutes:

() => ApiRoute[]
Returns the API routes for this channel (OAuth, webhooks, events). These are merged into the server's apiRoutes automatically.

initialize?:

() => Promise<void>
Called during Mastra initialization after all agents are registered. Use it for async setup such as restoring active installations. Does not provision new apps.

configure?:

(credentials: Record<string, unknown> | null) => void | Promise<void>
Provides or clears platform credentials at runtime. Pass null to clear credentials and delete stored tokens.

getInfo?:

() => ChannelPlatformInfo
Returns discovery metadata for the editor UI: platform name, configuration status, and the connect options schema.

connect?:

(agentId: string, options?: Record<string, unknown>) => Promise<ChannelConnectResult>
Connects an agent to the platform. Returns a discriminated result describing the authorization flow required to finish the connection.

disconnect?:

(agentId: string) => Promise<void>
Disconnects an agent from the platform. Deletes the platform app and cleans up stored state.

listInstallations?:

() => Promise<ChannelInstallationInfo[]>
Lists active installations for this platform. Returns public info only, never secrets.

Accessing a provider
Direct link to Accessing a provider

Access a registered provider through the channels getter, keyed by the id you registered it under. The getter is typed from the constructor config, so mastra.channels.slack is the concrete provider with its full method surface.

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

When the key is only known at runtime, look the provider up by string id instead. getChannelProvider takes the concrete type as a generic, and getChannelProviders returns every registered provider keyed by id.

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

const slack = mastra.getChannelProvider<SlackProvider>('slack')
const all = mastra.getChannelProviders()
On this page