Telegram Web Automation

You automate Telegram Web K via the browser-use CLI. Every action goes through a real browser — you read the DOM, click elements, type text, and scroll. No Telegram Bot API tokens are needed; the skill uses the web client directly.

Prerequisites

• browser-use CLI installed and on PATH
• A Telegram account (phone number linked)
• For headed mode: a display or X11 forwarding

Quickstart (new session)

Run this sequence every time you start a new session:

browser-use close --all                      # kill stale sessions (always first!)
sleep 1
browser-use --headed open https://web.telegram.org/k/
sleep 3                                      # wait for SPA to render
browser-use state                            # verify: chat list or QR code

QR code — user must scan with phone: Telegram → Settings → Devices → Link Desktop Device.

Chat list visible — logged in, proceed.

Persist login across sessions: use browser-use --profile "Default" --headed open https://web.telegram.org/k/ instead, or browser-use connect if the user has Chrome with remote debugging enabled.

Layout Reference

┌─────────────────────┐  ┌──────────────────────────────────────────┐
│ [Search bar]  [☰]   │  │  Chat header: name / subscribers / ⋮     │
│ [All][Folder1][...] │  │  ─────────────────────────────────────── │
│                     │  │                                         │
│ Chat 1  ────────────│  │  Messages / posts (scrollable)          │
│ Chat 2  ────────────│  │     • message text                      │
│ Channel ████████████│  │     • timestamps, views, reactions       │
│ Group   ────────────│  │     • sender name (in groups)           │
│                     │  │                                         │
│                     │  │  ─────────────────────────────────────── │
│                     │  │  [📎] [Message input] [😊] [▶ Send]     │
└─────────────────────┘  └──────────────────────────────────────────┘
   Left sidebar                  Main chat area

Chat list items show: contact/group/channel name, last message preview, timestamp, unread badge.

Conversation type indicators:

Header text	Type
"subscribers"	channel (one-way broadcast)
"members" or "group"	group chat
Online status / "last seen"	private chat
"Broadcast" label near input	channel posting mode

Core Workflows

1. Check New Messages

browser-use state                            # scan sidebar for unread badges
browser-use click <chat-index>               # open the chat
sleep 2
browser-use state                            # read messages

2. Read and Summarise Conversations

browser-use click <chat-index>
sleep 2
browser-use scroll down                      # loads older messages
browser-use scroll down
browser-use state                            # message text is inline

The state output IS the data source — messages appear as plain text with timestamps and sender labels.

For bulk extraction:

browser-use eval "(()=>{const b=document.querySelectorAll('.bubbles .bubble, [class*=\"messages-container\"] > div');return Array.from(b).map(m=>m.innerText).filter(t=>t.length>10).join('\\n---\\n')})()"

3. Send a Message

The message input is a contenteditable div, not a regular <input>. Use browser-use type, not browser-use input:

browser-use click <input-div-index>          # focus the contenteditable div
browser-use type "Hello everyone!"
browser-use keys "Enter"

For multiline messages: Shift+Enter for newline, Enter to send.

4. Reply to a Message

Method A — double-click:

browser-use dblclick <message-element-index>
sleep 1
browser-use state                            # input shows replying-to preview
browser-use type "My reply"
browser-use keys "Enter"

Method B — click then reply button:

browser-use click <message-index>
browser-use state                            # look for reply/forward buttons
browser-use click <reply-button-index>
browser-use type "My reply"
browser-use keys "Enter"

5. Post to a Channel / Group

Same as sending a message — navigate to the channel first:

browser-use click <channel-index>
sleep 2
browser-use state                            # verify "Broadcast" label near input
browser-use click <input-div-index>
browser-use type "Channel post content..."
browser-use keys "Enter"

Channel-specific actions (channels you own):

• Schedule: click ⋮ near send button → Schedule Message
• Silent send: right-click send button → Send without sound
• Edit: double-click your post → edit text → Enter to save

6. Search

browser-use click <search-index>
browser-use input <search-index> "search term"
browser-use keys "Enter"
sleep 1
browser-use state                            # results: Chats + Messages sections

Click a chat result to open conversation. Click a message result to jump to that message.

7. Bot Management (via @BotFather)

All bot management is done through the @BotFather chat. Open it via search:

browser-use click <search-index>
browser-use input <search-index> "BotFather"
browser-use keys "Enter"
sleep 1
browser-use state                            # BotFather under "Chats" section
browser-use click <botfather-result-index>

BotFather Interactive Buttons

After /mybots, BotFather sends clickable buttons. Prefer clicking them over typing commands:

Button	What it does
API Token	Shows the bot's HTTP API token
Edit Bot	Submenu: name, description, about, pic, commands
Bot Settings	Inline Mode, Groups, Privacy, Admin Rights, Payments
Payments	Configure payment providers
Transfer Bot	Transfer ownership to another user

Create a New Bot

browser-use type "/newbot"
browser-use keys "Enter"
sleep 1
browser-use state                            # "How are we going to call it?"
browser-use type "My Bot Display Name"       # display name (can be anything)
browser-use keys "Enter"
sleep 1
browser-use state                            # "choose a username ending in bot"
browser-use type "my_unique_bot_username"    # must be unique, must end with "bot"
browser-use keys "Enter"
sleep 1
browser-use state                            # BotFather replies with the API token

The token appears in the reply. Copy it immediately — you can always get it again via /mybots → API Token button.

Quick Command Reference

Command	Purpose
/newbot	Create a new bot (interactive wizard)
/mybots	List all your bots with management buttons
/token	Show a bot's API token
/revoke	Regenerate a bot's API token
/setname	Change bot display name
/setdescription	Change bot description
/setabouttext	Change bot bio/about
/setuserpic	Change bot profile photo
/setcommands	Set bot command menu
/deletebot	Delete a bot permanently
/cancel	Cancel the current operation

8. Create Group / Channel

browser-use click <menu-index>               # hamburger menu (top-left)
sleep 1
browser-use state
browser-use click <new-group-or-channel-index>
# Follow the creation wizard

9. Send Files / Media

browser-use click <attach-index>             # paperclip 📎 near input
sleep 1
browser-use upload <file-input-index> "/path/to/file.jpg"
sleep 1
browser-use type "Optional caption"
browser-use keys "Enter"

Essential JS Eval Snippets

# Check if logged in
browser-use eval "!!document.querySelector('.chatlist, [class*=\"chat-list\"], .chats-container, #column-left')"

# Count visible chats
browser-use eval "document.querySelectorAll('[id=\"column-left\"] a[href], .chatlist .chat, [class*=\"chatlist\"] [class*=\"item\"]').length"

# Get chat list names (first 15)
browser-use eval "Array.from(document.querySelectorAll('[id=\"column-left\"] [class*=\"peer-title\"], .chatlist .peer-title, [class*=\"chatlist\"] [class*=\"title\"]')).slice(0,15).map(el => el.innerText).join('\\n')"

# Get current chat name
browser-use eval "document.querySelector('[class*=\"chat-info\"] [class*=\"peer-title\"], [id=\"column-center\"] [class*=\"title\"] span')?.innerText || 'No chat selected'"

# Check if current conversation is a channel
browser-use eval "!!document.querySelector('[id=\"column-center\"]').innerText.match(/suscriber|broadcast|channel/i)"

Tips

1. Always browser-use close --all first — stale sessions cause hangs and timeouts. This is the #1 cause of startup failures.
2. Wait after navigation — Telegram Web K is a heavy SPA. Always sleep 2 after clicking a chat, sleep 1 after search.
3. Use browser-use type, not input — the message field is a contenteditable div. Click to focus, then type.
4. State IS the data — message text appears inline in browser-use state output. You rarely need eval for reading.
5. Session persistence — use browser-use --profile or browser-use connect to avoid re-login.
6. BotFather buttons > commands — after /mybots, click the interactive buttons instead of typing more commands.
7. Scroll lazily — messages load in pages. Scroll down 1-2 times for older messages.
8. Indices change — Telegram's DOM is dynamic. Always run state before clicking; never reuse indices from a previous state.
9. Rate limits — Telegram enforces flood control. Space sends at least 2 seconds apart.
10. Channel admin check — you can only post/edit/delete in channels where you have posting rights.

Troubleshooting

Problem	Fix
Command hangs / timeout	browser-use close --all — stale session is blocking
Page shows nothing after open	Wait 3-5 seconds, then state. SPA bootstraps slowly
Chat click doesn't open messages	Ensure chat is selected (bold in sidebar). Try clicking again or waiting
Search results not showing	After typing and Enter, wait 1-2 seconds, then state
input not typing into message field	Click the contenteditable div first, then use type instead of input
QR code instead of chats	Logged out. Scan QR: Telegram → Settings → Devices → Link Desktop
"Element not found" after navigation	DOM re-rendered — run state again for fresh indices
Stuck in BotFather wizard	Send /cancel to abort any in-progress operation
Bot creation fails with "Sorry"	Username taken or doesn't end with "bot". Try a more unique name
White screen after open	Close all: browser-use close --all, wait 2s, retry with --headed open

Cleanup

browser-use close                            # close current session
browser-use close --all                      # close ALL sessions (use between tasks)