agent-telegram

name	agent-telegram
description	Interact with Telegram through TDLib - authenticate, inspect chats, and send messages
version	2.12.2
allowed-tools	Bash(agent-telegram:*)

Agent Telegram

A TDLib-backed Telegram CLI for AI agents. The CLI auto-provisions API credentials via my.telegram.org — users never need to know or provide api_id/api_hash.

Use one of these entrypoints:

• Global install: agent-telegram ...
• One-off execution: bunx --package agent-messenger agent-telegram ...

Quick Start

# Login (CLI auto-provisions API credentials)
agent-telegram auth login --phone [phone]

# List chats
agent-telegram chat list

# Send a message
agent-telegram message send <chat-id-or-@username> "Hello from agent-telegram"

Authentication Flow

Telegram auth is stateful. TDLib persists authorization state locally, so each call picks up where the last one left off — no custom state management needed. The CLI automatically provisions API credentials via my.telegram.org during login — no manual credential setup required.

Agent Behavior (MANDATORY)

When a command fails because no account is configured, the agent MUST drive the auth flow itself. Never tell the user to run commands — the agent runs everything. Never mention api_id, api_hash, or my.telegram.org to the user — these are internal details handled by the CLI.

Step 1: Check for existing accounts

agent-telegram auth list

If accounts exist → agent-telegram auth use <account-id> and retry the original command.

Step 2: If no accounts, ask for phone number

Ask the user for their Telegram phone number (international format, e.g. [phone]). This is the ONLY thing the user needs to provide to start login.

Step 3: Start login — CLI auto-provisions API credentials

agent-telegram auth login --phone <phone>
# → {"next_action":"provide_provisioning_code","message":"A code was sent to your Telegram app. Provide it via --provisioning-code."}

The CLI sends a verification code to the user's Telegram app for credential provisioning. This is NOT the TDLib login code — it's for obtaining API credentials automatically.

Step 4: Ask user for the provisioning code, then provide it

agent-telegram auth login --phone <phone> --provisioning-code <code>
# → {"next_action":"provide_code","message":"Enter the code sent to your Telegram app via --code."}

After provisioning succeeds, the CLI continues to TDLib login and sends ANOTHER code to the user's Telegram app for actual authentication.

Step 5: Ask user for the TDLib login code, then provide it

agent-telegram auth login --code <code>
# → {"authenticated":true,...}
# or if 2FA enabled:
# → {"next_action":"provide_password","message":"2FA password required via --password."}

Step 6: If 2FA required, ask user for password, then provide it

agent-telegram auth login --password <password>

Step 7: Retry the original command

After successful auth, immediately execute whatever the user originally asked for.

IMPORTANT: Two separate codes

The login flow may require TWO codes from the user:

1. Provisioning code (via --provisioning-code) — for auto-obtaining API credentials from my.telegram.org
2. TDLib login code (via --code) — for Telegram account authentication

When asking the user for codes, be clear about which one you need. Say "I need the code sent to your Telegram app" for both — the user sees them as Telegram verification codes.

Common Auth Commands

agent-telegram auth status    # Check current state
agent-telegram auth list      # List stored accounts
agent-telegram auth use <id>  # Switch accounts
agent-telegram auth logout    # Logout

Common Commands

# Show current authenticated user
agent-telegram whoami
agent-telegram whoami --pretty
agent-telegram whoami --account <account-id>

# Search chats by title or username
agent-telegram chat search "project"

# Get chat metadata
agent-telegram chat get @durov

# List recent messages
agent-telegram message list @durov --limit 10

# Logout
agent-telegram auth logout

Notes

• Telegram phone numbers must be in international format, for example [phone].
• TDLib persists local account state under ~/.config/agent-messenger/telegram/.
• agent-telegram returns JSON by default and --pretty for indented output.