/agent-telegrambot

name: agent-telegrambot
description: Interact with Telegram using bot tokens - send messages, read chats, manage reactions
version: 2.38.0
allowed-tools: Bash(agent-telegrambot:*)
metadata:
  openclaw:
    requires:
      bins:
        - agent-telegrambot
    install:
      - kind: node
        package: agent-messenger
        bins: [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](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.

Key Concepts

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

• **Bot tokens** — Issued by talking to [@BotFather](https://t.me/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](https://t.me/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 edit <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: