Telegram
Telegram channels let people talk to your agent in Telegram direct messages, groups, and bot mentions.
Mastra Connect stores your Telegram bot token on the Mastra platform and registers the webhook for you. You can also manage the bot token and webhook yourself.
ConnectDirect link to Connect
Before you start, complete the Connect setup to install @mastra/connect and configure your platform project.
Connect uses a bot token from BotFather. Before you connect an agent, set MASTRA_ENCRYPTION_KEY on a persistent production server. Mastra uses it to encrypt the stored webhook secret. Without a key, the secret is stored unencrypted.
Webhook mode needs a public HTTPS server URL. Mastra platform supplies this URL. When you host elsewhere, set MASTRA_SERVER_URL to your public server URL. For local development without a public webhook URL, the Telegram provider reference describes polling mode.
-
Open BotFather, run
/newbot, and follow the prompts. -
Copy the bot token that BotFather returns.
-
Run
mastra connect add telegramand enter the bot token. -
Pass
channels()to theMastraconstructor. It registers the Telegram channel provider and its routes:src/mastra/index.tsimport { Mastra } from '@mastra/core'import { channels } from '@mastra/connect'import { assistant } from './agents/assistant'export const mastra = new Mastra({agents: { assistant },channels: await channels({ providers: ['telegram'] }),})To register other channels too, add their provider IDs to
providers. -
Start your Mastra application.
-
In Studio, connect the Telegram channel to an agent. Mastra verifies the bot, creates a webhook secret, and registers the agent's public webhook URL with Telegram.
To change an agent to a different bot, disconnect the agent in Studio, then connect it again. Mastra won't move an existing agent's webhook to another bot.
Self-managed setupDirect link to Self-managed setup
Use the Chat SDK Telegram adapter with your own bot token and webhook.
Install the adapterDirect link to Install the adapter
Install the Telegram adapter from the Chat SDK:
- npm
- pnpm
- Yarn
- Bun
npm install @chat-adapter/telegram
pnpm add @chat-adapter/telegram
yarn add @chat-adapter/telegram
bun add @chat-adapter/telegram
Agent configurationDirect link to Agent configuration
Add createTelegramAdapter() to the agent's channels.adapters object:
import { Agent } from '@mastra/core/agent'
import { createTelegramAdapter } from '@chat-adapter/telegram'
export const telegramAgent = new Agent({
id: 'telegram-agent',
name: 'Telegram Agent',
instructions: 'Answer questions and help with tasks in Telegram.',
model: 'openai/gpt-6.1-sol',
channels: {
adapters: {
telegram: createTelegramAdapter(),
},
},
})
Register the agent on the Mastra instance:
import { Mastra } from '@mastra/core'
import { telegramAgent } from './agents/telegram-agent'
export const mastra = new Mastra({
agents: { telegramAgent },
})
Adapter setupDirect link to Adapter setup
Follow the Chat SDK Telegram adapter docs for Telegram-specific setup, including BotFather, webhook registration, secret tokens, and polling mode.
The adapter reads Telegram credentials from environment variables such as:
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret-token
TELEGRAM_BOT_USERNAME=your_bot_username
Webhook URLDirect link to Webhook URL
Mastra generates the Telegram webhook route from the agent ID and adapter key:
/api/agents/telegram-agent/channels/telegram/webhook
Use your public Mastra server URL as the base URL:
https://your-app.example.com/api/agents/telegram-agent/channels/telegram/webhook
Use this URL anywhere the Telegram adapter docs ask for the webhook URL. Telegram also supports polling mode. Follow the Chat SDK adapter docs if you want to use polling for local development.