跳到主要内容
非官方简体中文翻译，内容版权归 Mastra 所有，遵循 Apache-2.0 许可。

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
Install the adapter的直接链接

Install the Telegram adapter from the Chat SDK:

npm install @chat-adapter/telegram

Agent configuration
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.6-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
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
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