Skip to main content

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.

Connect
Direct 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.

  1. Open BotFather, run /newbot, and follow the prompts.

  2. Copy the bot token that BotFather returns.

  3. Run mastra connect add telegram and enter the bot token.

  4. Pass channels() to the Mastra constructor. It registers the Telegram channel provider and its routes:

    src/mastra/index.ts
    import { 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.

  5. Start your Mastra application.

  6. 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 setup
Direct link to Self-managed setup

Use the Chat SDK Telegram adapter with your own bot token and webhook.

Install the adapter
Direct link to Install the adapter

Install the Telegram adapter from the Chat SDK:

npm install @chat-adapter/telegram

Agent configuration
Direct link to Agent configuration

Add createTelegramAdapter() to the agent's channels.adapters object:

src/mastra/agents/telegram-agent.ts
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:

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { telegramAgent } from './agents/telegram-agent'

export const mastra = new Mastra({
agents: { telegramAgent },
})

Adapter setup
Direct 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:

.env
TELEGRAM_BOT_TOKEN=your-telegram-bot-token
TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret-token
TELEGRAM_BOT_USERNAME=your_bot_username

Webhook URL
Direct 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.