| name | telegram-userbot |
| description | Подключение и работа с личным Telegram-аккаунтом владельца (userbot, НЕ бот). Используй, когда просят читать личные чаты/переписку/диалоги, искать по своим сообщениям, писать кому-то от своего имени, «зайди в мой телеграм», «подключи мой телеграм», «прочитай личку», «ответь в личке», «перешли сообщение», а также при первичном подключении аккаунта. Триггеры — «мой телеграм», «моя личка», «мои диалоги», «подключи аккаунт», «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-сервис; при первом подключении подними его сам.
- Проверь:
iva userbot status.
- Нужны
api_id / api_hash с my.telegram.org. Проведи владельца:
«Открой https://my.telegram.org → API development tools → создай приложение (название любое,
платформа Desktop) → пришли мне api_id и api_hash». Дождись, пока он пришлёт оба в чат.
- Запиши ключи (через stdin, БЕЗ утечки в список процессов):
iva userbot creds <<'CREDS'
<api_id>
<api_hash>
CREDS
- Подними прокси (сборка venv может занять ~1–2 мин — ставь
timeoutMs ≥ 300000):
iva userbot setup
Команда соберёт окружение, создаст токен и запустит сервис. iva перезапускать НЕ нужно.
Если iva не найден — запусти из каталога установки: node bin/iva.mjs userbot setup.
Шаг 3. Онбординг по QR (в чате)
- Вызови
qr_login_start. Сервер отрисует QR и сам пришлёт его картинкой в этот чат.
(Если сразу после setup вызов не прошёл — прокси ещё поднимается, повтори через несколько секунд.)
- Скажи владельцу: открой приложение Telegram того аккаунта, который подключаешь →
Настройки → Устройства → Подключить устройство → отсканируй QR.
- Опрашивай
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. Чтение почти
не банится — предпочитай его. Сомневаешься в отправке — замедлись или спроси владельца.
