# Telegram Userbot

> Личный Telegram владельца (userbot): читать чаты, искать, писать от его имени; подключение аккаунта.

- Skill: `smixs/telegram-userbot` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add smixs/telegram-userbot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/smixs/telegram-userbot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: smixs (https://skillmd.com/u/smixs)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/smixs/telegram-userbot

---


# telegram-userbot

Доступ к **личному Telegram-аккаунту владельца** (Telethon, MTProto) — отдельный аккаунт-человек,
НЕ бот, через которого ты сейчас общаешься. Всё делается ТОБОЙ прямо в этом чате: настройку ты
проводишь сам (через `bash`-тул на хосте), а работу — через MCP-тулы
`connection__telegram-userbot__<tool>` (ищи их через `connection_search`).
**Пользователь только пишет в чат — терминал он не трогает.**

## ⚠️ Сначала — предупреди и получи согласие

Автоматизация личного аккаунта нарушает ToS Telegram и может привести к **бану аккаунта**
(особенно отправка). Одной фразой скажи владельцу, что это на его страх и риск и что безопаснее
всего только чтение. Продолжай, только если он согласился.

## Шаг 1. Подключён ли аккаунт?

Вызови `login_status`.

- `connected` → всё готово, переходи к работе (Шаг 4).
- `not_connected` → нужен онбординг (Шаг 3), но сперва проверь, поднят ли прокси (Шаг 2).
- Если сам вызов падает (сервер недоступен) → прокси ещё не установлен, иди в Шаг 2.

## Шаг 2. Поднять прокси (первый раз, делаешь ты через `bash`)

Прокси — opt-in Python-сервис; при первом подключении подними его сам.

1. Проверь: `iva userbot status`.
2. Нужны `api_id` / `api_hash` с my.telegram.org. Проведи владельца:
   «Открой https://my.telegram.org → **API development tools** → создай приложение (название любое,
   платформа Desktop) → пришли мне **api_id** и **api_hash**». Дождись, пока он пришлёт оба в чат.
3. Запиши ключи (через stdin, БЕЗ утечки в список процессов):
   ```bash
   iva userbot creds <<'CREDS'
   <api_id>
   <api_hash>
   CREDS
   ```
4. Подними прокси (сборка venv может занять ~1–2 мин — ставь `timeoutMs` ≥ 300000):
   ```bash
   iva userbot setup
   ```
   Команда соберёт окружение, создаст токен и запустит сервис. **iva перезапускать НЕ нужно.**
   Если `iva` не найден — запусти из каталога установки: `node bin/iva.mjs userbot setup`.

## Шаг 3. Онбординг по QR (в чате)

1. Вызови `qr_login_start`. Сервер отрисует QR и **сам пришлёт его картинкой в этот чат**.
   (Если сразу после setup вызов не прошёл — прокси ещё поднимается, повтори через несколько секунд.)
2. Скажи владельцу: открой приложение Telegram **того аккаунта, который подключаешь** →
   Настройки → Устройства → Подключить устройство → отсканируй QR.
3. Опрашивай `qr_login_status` раз в несколько секунд:
   - `authorized` → готово.
   - `password_needed` → включена двухфакторка. Попроси у владельца пароль и передай в
     `qr_login_password`. **Предупреди:** пароль пройдёт через чат — пусть сменит его потом, если
     переживает. Не логируй и не повторяй пароль в ответах.
   - `waiting` → ещё не отсканировал, подожди.
   - `expired` / `error` → начни заново с `qr_login_start`, объясни причину.

Сессия хранится на сервере — повторный онбординг после рестарта не нужен.

## Шаг 4. Работа с аккаунтом

Ходовые тулы (полный список — `connection_search`):

- Чтение: `get_chats`, `get_dialogs_json`, `get_history`, `list_messages`, `get_messages`.
- Поиск: `search_messages` (внутри чата), `search_global`, `resolve_username`.
- Отправка: `send_message`, `reply_to_message`, `send_file`, `forward_message`.

## Анти-бан — обязательно

Сервер уже принудительно соблюдает FloodWait и притормаживает отправки, но лимиты Telegram —
на уровне аккаунта. **Перед любой отправкой прочитай `safety.md` в этом скилле** и следуй ему:
рандомные паузы, не бомбить, не слать одинаковый текст веером, стоп при `PeerFlood`. Чтение почти
не банится — предпочитай его. Сомневаешься в отправке — замедлись или спроси владельца.