ContextQMD
Back to Eliza

Telegram Plugin

packages/docs/plugin-registry/platform/telegram.md

2.0.14.0 KB
Original Source

The Telegram plugin connects Eliza agents to Telegram as a bot, handling private messages, group chats, inline queries, and media sharing.

Package: @elizaos/plugin-telegram

Installation

bash
eliza plugins install @elizaos/plugin-telegram

Setup

1. Create a Telegram Bot

  1. Open Telegram and message @BotFather
  2. Send /newbot and follow the prompts
  3. BotFather will give you a bot token in the format 123456789:ABCdef...

2. Configure Eliza

json
{
  "connectors": {
    "telegram": {
      "botToken": "123456789:ABCdef..."
    }
  }
}

Or via environment variable:

bash
export TELEGRAM_BOT_TOKEN=123456789:ABCdef...

Configuration

FieldRequiredDescription
botTokenYesTelegram bot token from BotFather
enabledNoSet false to disable (default: true)
dmPolicyNoDM access policy: "pairing", "allowlist", "open", or "disabled" (default: "pairing")
allowFromNoUser IDs allowed to DM (required when dmPolicy is "open", must include "*")
groupPolicyNoGroup join policy: "open", "disabled", or "allowlist" (default: "allowlist")
webhookUrlNoUse webhook instead of polling (requires HTTPS URL)
webhookSecretNoSecret token for webhook verification (required when webhookUrl is set)
json
{
  "connectors": {
    "telegram": {
      "botToken": "123456789:ABCdef...",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "groups": {
        "-1001234567890": {
          "requireMention": true
        }
      }
    }
  }
}

Features

  • Private messages — 1:1 conversations with users
  • Group chats — Responds in groups when mentioned or replied to
  • Channels — Can post to Telegram channels
  • Inline queries — Responds to @botname query inline in any chat
  • Media — Handles photos, documents, audio, video
  • Commands — Responds to /command style messages
  • Webhooks — Supports webhook mode for production deployments
  • Long polling — Default mode for development

Message Flow

Telegram Update (via polling or webhook)
       ↓
Plugin processes update type:
  - message → route to AgentRuntime
  - callback_query → handle button press
  - inline_query → handle inline search
       ↓
Determines response target (chat_id)
       ↓
AgentRuntime processes message
       ↓
Response sent via Telegram Bot API

Group Behavior

In group chats, the agent responds only when:

  • The bot is mentioned (@botname)
  • A message is a reply to the bot's message
  • The message starts with a configured command

To have the bot respond to all messages in a group, set allowedGroups and configure the character to respond more broadly.

Webhook Mode

For production deployments, webhook mode is more reliable than polling:

json
{
  "connectors": {
    "telegram": {
      "botToken": "123456789:ABCdef...",
      "webhookUrl": "https://your-domain.com/webhook/telegram",
      "webhookSecret": "your-random-secret"
    }
  }
}

The webhook endpoint must be accessible over HTTPS.

Environment Variables

VariableRequiredDescription
TELEGRAM_BOT_TOKENYesTelegram bot token from BotFather
TELEGRAM_API_ROOTNoCustom Telegram Bot API root URL
TELEGRAM_ALLOWED_CHATSNoComma-separated list of allowed chat IDs
TELEGRAM_TEST_CHAT_IDNoChat ID for test/dev messages

Auto-Enable

The plugin auto-enables when connectors.telegram.botToken is set.