Help us improve
Share bugs, ideas, or general feedback.
From agent-messenger
Provides CLI for Telegram Bot API using bot tokens: authenticate, send messages, read chats, get info, manage multi-bot setups. For CI/CD and server-side messaging automation.
npx claudepluginhub agent-messenger/agent-messenger --plugin agent-channeltalkbotHow this skill is triggered — by the user, by Claude, or both
Slash command
/agent-messenger:agent-telegrambotThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
A TypeScript CLI tool that enables AI agents and humans to interact with Telegram using **Bot API tokens** (the kind issued by [@BotFather](https://t.me/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.
Implements Telegram bots with full Bot API support: BotFather setup, messages, webhooks, inline keyboards, groups, channels. Node.js and Python boilerplates.
Interacts with Telegram via TDLib CLI: authenticate accounts with auto-provisioned credentials, list/inspect chats, send messages. For AI agent Telegram integrations.
Automates Telegram bot tasks: send messages/media, manage chats, handle commands via Composio toolkit and Rube MCP. Requires active Rube MCP/Telegram connection.
Share bugs, ideas, or general feedback.
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.
Before diving in, a few things about Telegram Bot integration:
123456789:ABC-DEF1234ghIkl-zyx57W2v1u123ew11. Bot acts as its own bot account, with a username ending in bot./start the bot first. In groups, bots receive only messages mentioning them or commands unless privacy mode is disabled in BotFather settings.@channelusername.getUpdates), not via the CLI. Telegram Bot API does not support WebSockets.# Set your bot token (validates against Telegram)
agent-telegrambot auth set 123456789:ABC-DEF1234...
# Verify authentication
agent-telegrambot whoami
# Send a message
agent-telegrambot message send @username "Hello from bot!"
# Get chat info
agent-telegrambot chat info @somegroup
agent-telegrambot uses Bot API tokens which you create by chatting with @BotFather:
# Set bot token (validates against Telegram API before saving)
agent-telegrambot auth set 123456789:ABC-DEF1234...
# Set with a custom bot identifier
agent-telegrambot auth set <token> --bot deploy
# Check auth status
agent-telegrambot auth status
# Clear stored credentials
agent-telegrambot auth clear
# List all configured bots
agent-telegrambot auth list
# Switch active bot
agent-telegrambot auth use <bot-id>
# Remove a bot
agent-telegrambot auth remove <bot-id>
# Use a specific bot for a single command
agent-telegrambot --bot deploy message send @channel "Deploy succeeded"
The agent maintains a ~/.config/agent-messenger/MEMORY.md file as persistent memory across sessions. This is agent-managed — the CLI does not read or write this file. Use the Read and Write tools to manage your memory file.
-1001234567890 → "alerts channel")123456789 → "Alice")Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and chat context).
# Agent Messenger Memory
## Telegram Bots
- `deploy` — Deploy Bot (active)
- `alert` — Alert Bot
## Chats (Deploy Bot)
- `-1001234567890` — #ci-alerts (channel)
- `-1009876543210` — Engineering (supergroup)
- `123456789` — Alice (DM)
## Aliases
- "alerts" → `-1001234567890`
# Set bot token
agent-telegrambot auth set <token>
agent-telegrambot auth set <token> --bot deploy
# Check auth status
agent-telegrambot auth status
agent-telegrambot auth status --bot deploy
# Clear all credentials
agent-telegrambot auth clear
# List stored bots
agent-telegrambot auth list
# Switch active bot
agent-telegrambot auth use <bot-id>
# Remove a stored bot
agent-telegrambot auth remove <bot-id>
# Show current authenticated bot
agent-telegrambot whoami
agent-telegrambot whoami --pretty
agent-telegrambot whoami --bot <bot-id>
# Send a text message
agent-telegrambot message send <chat> <text>
agent-telegrambot message send @username "Hello"
agent-telegrambot message send -1001234567890 "Hello channel"
# Send with formatting
agent-telegrambot message send @username "<b>Bold</b> message" --parse-mode HTML
# Reply to a specific message
agent-telegrambot message send @username "Reply text" --reply-to 12345
# Send silently (no notification)
agent-telegrambot message send @username "Silent message" --silent
# Send to a forum topic
agent-telegrambot message send <chat> "Topic message" --thread-id 5
# Edit a message (bot's own messages only)
agent-telegrambot message update <chat> <message-id> <new-text>
# Delete a message
agent-telegrambot message delete <chat> <message-id> --force
# Forward a message between chats
agent-telegrambot message forward <to-chat> <from-chat> <message-id>
# Upload a document
agent-telegrambot message upload <chat> ./report.pdf --caption "Daily report"
# Get chat info
agent-telegrambot chat info <chat>
agent-telegrambot chat info @somegroup
agent-telegrambot chat info -1001234567890
# Get chat member info
agent-telegrambot chat member <chat> <user-id>
# Set a reaction (replaces any existing reaction by the bot)
agent-telegrambot reaction set <chat> <message-id> 👍
agent-telegrambot reaction set <chat> <message-id> 👍 --big
# Clear all reactions
agent-telegrambot reaction clear <chat> <message-id>
All commands output JSON by default for AI consumption:
{
"message": {
"message_id": 42,
"chat_id": -1001234567890,
"text": "Hello",
"from": "mybot",
"date": 1735689600
}
}
Use --pretty flag for formatted output:
agent-telegrambot message send @username "Hello" --pretty
| Option | Description |
|---|---|
--pretty | Human-readable output instead of JSON |
--bot <id> | Use a specific bot for this command |
The <chat> argument accepts:
123456789 (user), -1001234567890 (channel/supergroup)@channelname, @username (must be public)channelname (auto-prefixed with @)Bots cannot DM a user who has never started a chat with the bot. The user must send /start first.
Real-time events are NOT available in the CLI but ARE available via the SDK using long-polling:
import { TelegramBotClient, TelegramBotListener } from 'agent-messenger/telegrambot'
const client = await new TelegramBotClient().login({ token: 'YOUR_BOT_TOKEN' })
const listener = new TelegramBotListener(client, {
allowedUpdates: ['message', 'callback_query'],
})
listener.on('message', (msg) => {
console.log(`From ${msg.chat.id}: ${msg.text}`)
})
await listener.start()
Long-polling means the bot opens a long-lived HTTPS connection that the server holds open until updates arrive. No public endpoint is required — perfect for CI/CD and behind-NAT environments.
All commands return consistent error format:
{
"error": "Forbidden: bot can't initiate conversation with a user"
}
Common errors:
Unauthorized — Invalid or revoked bot token. Generate a new token via @BotFather.Forbidden — Bot was kicked from chat, or user hasn't started the bot, or bot lacks permissions.Bad Request: chat not found — Wrong chat ID, or the bot isn't a member of that chat.Conflict — Another getUpdates call is in progress (only one polling instance allowed per bot).Too Many Requests — Rate limited; the client automatically retries after the retry_after interval.Credentials stored in ~/.config/agent-messenger/telegrambot-credentials.json (0600 permissions). The location can be overridden with AGENT_MESSENGER_CONFIG_DIR.
| Feature | agent-telegram (TDLib) | agent-telegrambot (Bot API) |
|---|---|---|
| Token type | User session (TDLib) | Bot token (BotFather) |
| Auth | Phone + code, stateful | One-time token from BotFather |
| Initiate DMs | Yes | No (user must /start first) |
| Read all group msgs | Yes | Only with privacy mode disabled |
| ToS for automation | Grey area at scale | Officially sanctioned |
| CI/CD friendly | Possible (persist auth state) | Yes (just set token) |
| Real-time events | Yes (TDLib updates) | Yes (long-polling getUpdates) |
| Inline keyboards | No | Yes (via SDK) |
/start firstgetUpdates polling instance can run per bot (Telegram returns 409 Conflict otherwise)agent-telegrambot: command not foundagent-telegrambot is NOT the npm package name. The npm package is agent-messenger.
If the package is installed globally, use agent-telegrambot directly:
agent-telegrambot message send @username "Hello"
If the package is NOT installed, use npx -y by default:
npx -y agent-messenger telegrambot message send @username "Hello"
bunx agent-messenger telegrambot message send @username "Hello"
pnpm dlx agent-messenger telegrambot message send @username "Hello"
If you already know the user's preferred package runner (e.g.,
bunx,pnpm dlx), use that instead.
NEVER run npx agent-telegrambot, bunx agent-telegrambot, or pnpm dlx agent-telegrambot — it will fail or install a wrong package since agent-telegrambot is not the npm package name.
The user has never started a chat with the bot. They need to find the bot in Telegram and tap Start (or send /start) before the bot can message them.
Another instance (or a stale webhook) is polling the same bot. Stop other instances, or run:
# Through the SDK or curl - no CLI helper for this yet
curl "https://api.telegram.org/bot<TOKEN>/deleteWebhook?drop_pending_updates=true"
Either the chat ID is wrong, the username is misspelled, or the bot isn't a member of that chat. Make sure the bot has been added to the group/channel and (for channels) given posting permission.