Telegram Personal CLI (via Telethon)

A CLI for reading and managing my own Telegram account's conversations (DMs, groups, channels) — separate from the OpenClaw Telegram bot channel, which only sees messages sent to the bot.

Location

/Users/dominick/Work/llm/skills/telegram/ — an OpenClaw skill (env.sh + telegram-cli wrapper + scripts/telegram.py, following the same convention as the notion skill).

Auth

• Uses the Telegram Client API (api_id / api_hash), not the Bot API. These identify an app allowed to log into my personal account — different from a bot token.
• Got credentials from https://my.telegram.org/apps. That form is finicky: short name must be lowercase letters/numbers only (5–32 chars, no hyphens/underscores) or it silently errors with a 200 response; also helps to leave URL/description blank and avoid VPN.
• Credentials live in the skill-local env.sh (gitignored), never in chat.
• First login is interactive (phone number + Telegram-sent code + 2FA password) — run ./telegram-cli login myself in a terminal, not through the assistant. Saves a local telegram.session file; everything after that is non-interactive.

Commands (as of 2026-09-12)

Read-only:

• dialogs — list all conversations (id, name, type, username, unread count)
• messages <chat> [--search] [--since] — fetch messages from one chat
• search <query> [--chat] — search message text, one chat or across all
• export <chat> --out file.json — dump a chat's full history to JSON

Actions:

• delete <chat> --yes — clear a conversation from my account view (doesn't notify the other side)
• send <chat> "text" --yes
• mark-read <chat> / archive <chat> / unarchive <chat> — reversible, no --yes needed
• block <chat> --yes / unblock <chat>
• report <chat> [--message] --yes — submits an actual spam report to Telegram (better than delete alone for real scammers, since it flags the account platform-side)
• download-media <chat> --out dir — save photos/videos/docs/voice notes from a chat

All commands print JSON (--pretty for indented output, placed after the subcommand).

Why this exists

Built 2026-09-12 after noticing a pattern of "wrong number" / romance-scam-style DMs sitting unread in Telegram — generic openers like "hi", "I am Janet. What is you are name?", "Finley?" from accounts with no username and either a numeric-only display name or a garbled one. Found and deleted 9 of these on the first pass (one, "Leanne," had a normal-looking name but the same vague-opener pattern and got caught on a second look at message content, not just the dialog list).

Follow-ups / not yet built

Higher-effort capabilities considered but deliberately deferred:

• Live listening — Telethon supports real-time event handlers for new messages, but that's a standing background process, not a one-shot CLI call. Would need its own design (where it runs, how it notifies me) rather than just another subcommand.
• Group/channel management — join/leave, kick members, promote admins, edit group settings.
• Single-message edit/delete — current delete clears a whole conversation, not one message.
• Contacts management — add/remove/list saved contacts.
• Reactions, pinning, polls.
• Account-level settings (2FA, phone number, privacy) — would want to explicitly decide on these case by case rather than pre-build, since they affect the account itself, not just messages.

Facebook Messenger (for comparison)

No equivalent path exists. Meta doesn't offer a personal-DM API — the Graph API only covers Messenger for Pages/businesses. Only sanctioned way to get personal Messenger history is Meta's "Download Your Information" export (Settings → Your Information → Download Your Information), which is a manual JSON/HTML archive, not a live CLI/API.