Skip to main content

Telegram

Telegram channels let a Mastra agent receive direct messages, group messages, and bot mentions from Telegram. Mastra handles the agent wiring and webhook route; the Chat SDK Telegram adapter docs cover bot setup, webhook registration, and polling behavior.

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-5.5',
  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.

On this page