agent-telegrambot

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...

# Verify authentication
agent-telegrambot whoami

# Send a message
agent-telegrambot message send @username "Hello from bot!"

# Get chat info
agent-telegrambot chat info @somegroup

Authentication

Bot Token Setup

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

Multi-Bot Support

# 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"

Memory

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.

What to Store

• Chat IDs with names (e.g. -1001234567890 → "alerts channel")
• User IDs with display names (e.g. 123456789 → "Alice")
• Bot identifiers and their purposes
• User-given aliases ("the alerts bot", "the team channel")

What NOT to Store

Never store bot tokens, credentials, or any sensitive data. Never store full message content (just IDs and chat context).

Format / Example

# 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`

Commands

Auth Commands

# 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>

Whoami Command

# Show current authenticated bot
agent-telegrambot whoami
agent-telegrambot whoami --pretty
agent-telegrambot whoami --bot <bot-id>

Message Commands

# 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"

Chat Commands

# 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>

Reaction Commands

# 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>

Output Format

JSON (Default)

All commands output JSON by default for AI consumption:

{
  "message": {
    "message_id": 42,
    "chat_id": -1001234567890,
    "text": "Hello",
    "from": "mybot",
    "date": 1735689600
  }
}

Pretty (Human-Readable)

Use --pretty flag for formatted output:

agent-telegrambot message send @username "Hello" --pretty

Global Options

Option	Description
--pretty	Human-readable output instead of JSON
--bot <id>	Use a specific bot for this command

Chat ID Resolution

The <chat> argument accepts:

• Numeric ID: 123456789 (user), -1001234567890 (channel/supergroup)
• @username: @channelname, @username (must be public)
• Plain username: 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

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.

Error Handling

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.

Configuration

Credentials stored in ~/.config/agent-messenger/telegrambot-credentials.json (0600 permissions). The location can be overridden with AGENT_MESSENGER_CONFIG_DIR.

Key Differences from agent-telegram

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)

Limitations

• Bots cannot initiate DMs — user must send /start first
• Bots cannot read group messages by default (privacy mode is on by default; turn it off via @BotFather for full access, or grant admin)
• Bot can only edit/delete its own messages, except in groups where it has delete permissions
• Plain text messages with optional HTML/Markdown parse modes (no inline keyboards from the CLI yet — use the SDK)
• File uploads use multipart/form-data; max 50MB per file via the standard Bot API server
• Only one getUpdates polling instance can run per bot (Telegram returns 409 Conflict otherwise)

Troubleshooting

agent-telegrambot: command not found

agent-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.

"Forbidden: bot can't initiate conversation with a user"

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.

"Conflict: terminated by other getUpdates request"

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"

"Bad Request: chat not found"

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.