Back to Details

agent-telegram

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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 ...
一款基于TDLib的面向AI Agent的Telegram命令行工具（CLI）。该CLI可通过my.telegram.org自动获取API凭证——用户无需知晓或提供api_id/api_hash。
使用以下任一方式启动：
  • 全局安装后使用：
    agent-telegram ...
  • 一次性执行：
    bunx --package agent-messenger agent-telegram ...

Quick Start

快速开始

bash
undefined
bash
undefined

Login (CLI auto-provisions API credentials)

登录（CLI自动获取API凭证）

agent-telegram auth login --phone +821012345678
agent-telegram auth login --phone +821012345678

List chats

列出聊天列表

agent-telegram chat list
agent-telegram chat list

Send a message

发送消息

agent-telegram message send chat-id-or-@username "Hello from agent-telegram"
undefined
agent-telegram message send chat-id-or-@username "Hello from agent-telegram"
undefined

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.
Telegram身份验证是有状态的。TDLib会在本地持久化授权状态，因此每次调用都会接续上次的状态——无需自定义状态管理。登录期间，CLI会通过my.telegram.org自动获取API凭证——无需手动配置凭证。

Agent Behavior (MANDATORY)

Agent行为规范（必须遵守）

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
bash
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. 
+821012345678
). This is the ONLY thing the user needs to provide to start login.
Step 3: Start login — CLI auto-provisions API credentials
bash
agent-telegram auth login --phone <phone>
当命令因未配置账户而失败时，Agent必须自行引导完成身份验证流程。绝不能让用户手动运行命令——所有操作都由Agent执行。绝不能向用户提及api_id、api_hash或my.telegram.org——这些都是CLI内部处理的细节。
步骤1：检查现有账户
bash
agent-telegram auth list
如果存在账户 → 执行
agent-telegram auth use <account-id>
，然后重试原命令。
步骤2：若无账户，请求用户提供电话号码
向用户索要其Telegram电话号码（国际格式，例如
+821012345678
）。这是用户启动登录流程唯一需要提供的信息。
步骤3：启动登录——CLI自动获取API凭证
bash
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."}

→ {"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**

```bash
agent-telegram auth login --phone <phone> --provisioning-code <code>

CLI会向用户的Telegram应用发送一个验证码，用于获取凭证。这不是TDLib的登录验证码——而是用于自动获取API凭证的验证码。

**步骤4：请求用户提供凭证验证码，然后传入**

```bash
agent-telegram auth login --phone <phone> --provisioning-code <code>

→ {"next_action":"provide_code","message":"Enter the code sent to your Telegram app via --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**

```bash
agent-telegram auth login --code <code>

凭证获取成功后，CLI会继续执行TDLib登录流程，并向用户的Telegram应用发送另一个验证码，用于实际的账户身份验证。

**步骤5：请求用户提供TDLib登录验证码，然后传入**

```bash
agent-telegram auth login --code <code>

→ {"authenticated":true,...}

→ {"authenticated":true,...}

or if 2FA enabled:

若启用了双因素认证：

→ {"next_action":"provide_password","message":"2FA password required via --password."}

→ {"next_action":"provide_password","message":"2FA password required via --password."}


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

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

**步骤6：若需双因素认证，请求用户提供密码，然后传入**

```bash
agent-telegram auth login --password <password>
步骤7：重试原命令
身份验证成功后，立即执行用户最初请求的操作。
重要提示：两个不同的验证码
登录流程可能需要用户提供两个验证码：
  1. 凭证验证码（通过
    --provisioning-code
    传入）——用于从my.telegram.org自动获取API凭证
  2. TDLib登录验证码（通过
    --code
    传入）——用于Telegram账户身份验证
向用户索要验证码时，需明确说明需要哪一个。对于两者，都可以说“需要您Telegram应用中收到的验证码”——用户会将它们视为Telegram验证码。

Common Auth Commands

常用身份验证命令

bash
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
bash
agent-telegram auth status    # 检查当前状态
agent-telegram auth list      # 列出已存储的账户
agent-telegram auth use <id>  # 切换账户
agent-telegram auth logout    # 登出

Common Commands

常用命令

bash
undefined
bash
undefined

Show current authenticated user

显示当前已认证用户

agent-telegram whoami agent-telegram whoami --pretty agent-telegram whoami --account <account-id>
agent-telegram whoami agent-telegram whoami --pretty agent-telegram whoami --account <account-id>

Search chats by title or username

按标题或用户名搜索聊天

agent-telegram chat search "project"
agent-telegram chat search "project"

Get chat metadata

获取聊天元数据

agent-telegram chat get @durov
agent-telegram chat get @durov

List recent messages

列出最近的消息

agent-telegram message list @durov --limit 10
agent-telegram message list @durov --limit 10

Logout

登出

agent-telegram auth logout
undefined
agent-telegram auth logout
undefined

Notes

注意事项

  • Telegram phone numbers must be in international format, for example 
    +14155551234
    .
  • TDLib persists local account state under 
    ~/.config/agent-messenger/telegram/
    .
  • agent-telegram
    returns JSON by default and 
    --pretty
    for indented output.
  • Telegram电话号码必须使用国际格式，例如
    +14155551234
    。
  • TDLib会在
    ~/.config/agent-messenger/telegram/
    目录下持久化本地账户状态。
  • agent-telegram
    默认返回JSON格式数据，添加
    --pretty
    参数可获取格式化后的缩进输出。