Agent TelegramBot

A TypeScript CLI tool that enables AI agents and humans to interact with Telegram using Bot API tokens (the kind issued by @BotFather). Unlike agent-telegram which authenticates as a real user account via TDLib, agent-telegrambot uses Telegram's HTTP Bot API — designed for server-side and CI/CD integrations.

Key Concepts

Before diving in, a few things about Telegram Bot integration:

• Bot tokens — Issued by talking to @BotFather inside Telegram. Format: 123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Bot acts as its own bot account, with a username ending in bot.
• Bot ≠ User — Bots cannot initiate DMs. The user must /start the bot first. In groups, bots receive only messages mentioning them or commands unless privacy mode is disabled in BotFather settings.
• Chat IDs — Numeric IDs (positive for users, negative for groups, very negative for supergroups/channels). Channels can also be referenced by @channelusername.
• Real-time events — Available via the SDK's long-polling listener (getUpdates), not via the CLI. Telegram Bot API does not support WebSockets.
• Webhook vs polling — A bot can use webhooks OR long-polling, not both. The SDK listener auto-disables any active webhook before polling.

Quick Start

# Set your bot token (validates against Telegram)
agent-telegrambot auth set 123456789:ABC-DEF1234...