packages/docs/connectors/telegram.md
Connect your agent to Telegram for private chats and group conversations using the @elizaos/plugin-telegram package.
| Name | Required | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather |
TELEGRAM_API_ROOT | No | Base URL for Telegram Bot API (allows overriding the default endpoint) |
TELEGRAM_ALLOWED_CHATS | No | JSON-encoded array of chat IDs authorized to interact with the bot |
TELEGRAM_TEST_CHAT_ID | No | Chat ID used by the test suite for validation |
The connector auto-enables when botToken, token, or apiKey is truthy in the connector config and enabled is not explicitly false.
Configure in ~/.eliza/eliza.json:
{
"connectors": {
"telegram": {
"botToken": "your-telegram-bot-token"
}
}
}
To explicitly disable the connector even when a token is present:
{
"connectors": {
"telegram": {
"botToken": "your-telegram-bot-token",
"enabled": false
}
}
}
/newbot to create a new bot and copy the bot token.connectors.telegram.botToken in your config.When the connector is loaded, the runtime pushes the following secret from your config into process.env for the plugin to consume:
| Variable | Required | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN | Yes | Bot token from @BotFather |
TELEGRAM_API_ROOT | No | Override the default Telegram Bot API base URL |
TELEGRAM_ALLOWED_CHATS | No | JSON-encoded array of authorized chat IDs |
All fields are defined under connectors.telegram in eliza.json.
| Field | Type | Default | Description |
|---|---|---|---|
botToken | string | — | Bot token from BotFather |
tokenFile | string | — | Path to file containing bot token (alternative to inline) |
name | string | — | Account display name |
enabled | boolean | — | Explicitly enable/disable |
capabilities | string[] or object | — | Capability flags. Object form supports inlineButtons: "off", "dm", "group", "all", or "allowlist" |
dmPolicy | "pairing" | "allowlist" | "open" | "disabled" | "pairing" | DM access policy. "open" requires allowFrom to include "*" |
allowFrom | (string|number)[] | — | User IDs allowed to DM |
groupPolicy | "open" | "disabled" | "allowlist" | "allowlist" | Group join policy |
groupAllowFrom | (string|number)[] | — | User IDs allowed in groups |
historyLimit | integer >= 0 | — | Max messages in context |
dmHistoryLimit | integer >= 0 | — | History limit for DMs |
dms | object | — | Per-DM history overrides keyed by DM ID. Each value: {historyLimit?: int} |
textChunkLimit | integer > 0 | — | Max characters per message chunk |
chunkMode | "length" | "newline" | — | Long message splitting strategy |
mediaMaxMb | number > 0 | — | Max media file size in MB |
configWrites | boolean | true | Allow config writes from Telegram events |
replyToMode | "off" | "first" | "all" | — | Reply threading mode |
linkPreview | boolean | — | Enable/disable link previews |
timeoutSeconds | integer > 0 | 500 | grammY request timeout |
proxy | string | — | Proxy URL for Telegram API requests |
markdown | object | — | Table rendering: tables can be "off", "bullets", or "code" |
commands | object | — | native and nativeSkills command toggles |
| Field | Type | Default | Description |
|---|---|---|---|
streamMode | "off" | "partial" | "block" | "partial" | "partial" sends incremental message edits. "block" waits for full response. "off" disables streaming |
blockStreaming | boolean | — | Disable streaming entirely |
blockStreamingCoalesce | object | — | Coalescing settings: minChars, maxChars, idleMs |
draftChunk | object | — | Draft chunking settings (see below) |
Draft chunk controls how partial streaming messages are split:
| Field | Type | Description |
|---|---|---|
draftChunk.minChars | integer | Minimum characters before sending a draft |
draftChunk.maxChars | integer | Maximum characters per draft chunk |
draftChunk.breakPreference | "paragraph" | "newline" | "sentence" | Where to prefer breaking drafts |
| Field | Type | Description |
|---|---|---|
actions.reactions | boolean | Send reactions |
actions.sendMessage | boolean | Send messages |
actions.deleteMessage | boolean | Delete messages |
actions.sticker | boolean | Send stickers |
| Field | Type | Description |
|---|---|---|
reactionNotifications | "off" | "own" | "all" | Which reactions trigger notifications |
reactionLevel | "off" | "ack" | "minimal" | "extensive" | Reaction response verbosity |
Define custom entries in the Telegram bot command menu:
{
"connectors": {
"telegram": {
"customCommands": [
{ "command": "status", "description": "Check agent status" },
{ "command": "help", "description": "Show help message" }
]
}
}
}
Per-group settings are defined under groups.<group-id>:
| Field | Type | Description |
|---|---|---|
requireMention | boolean | Only respond when @mentioned |
tools | ToolPolicySchema | Tool access policy |
toolsBySender | object | Per-sender tool policies (keyed by sender ID) |
skills | string[] | Allowed skills |
enabled | boolean | Enable/disable this group |
allowFrom | (string|number)[] | Allowed user IDs |
systemPrompt | string | Group-specific system prompt |
Per-topic settings are defined within a group under groups.<group-id>.topics.<topic-id>:
| Field | Type | Description |
|---|---|---|
requireMention | boolean | Only respond when @mentioned |
skills | string[] | Allowed skills |
enabled | boolean | Enable/disable this topic |
allowFrom | (string|number)[] | Allowed user IDs |
systemPrompt | string | Topic-specific system prompt |
For production deployments, use webhooks instead of polling:
{
"connectors": {
"telegram": {
"webhookUrl": "https://your-domain.com/telegram/webhook",
"webhookSecret": "your-webhook-secret",
"webhookPath": "/telegram/webhook"
}
}
}
When webhookUrl is set, webhookSecret is required.
| Field | Type | Description |
|---|---|---|
network.autoSelectFamily | boolean | Auto-select IPv4/IPv6 |
retry.attempts | integer | Max retry attempts |
retry.minDelayMs | integer | Minimum retry delay |
retry.maxDelayMs | integer | Maximum retry delay |
retry.jitter | number | Jitter factor |
{
"connectors": {
"telegram": {
"heartbeat": {
"showOk": true,
"showAlerts": true,
"useIndicator": true
}
}
}
}
The accounts field allows running multiple Telegram bots from a single agent:
{
"connectors": {
"telegram": {
"accounts": {
"bot-1": { "botToken": "...", "groups": { } },
"bot-2": { "botToken": "...", "groups": { } }
}
}
}
}