telegram-userbot

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-сервис; при первом подключении подними его сам.

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, БЕЗ утечки в список процессов):

   iva userbot creds <<'CREDS'
   <api_id>
   <api_hash>
   CREDS
   

4. Подними прокси (сборка venv может занять ~1–2 мин — ставь timeoutMs ≥ 300000):

   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. Чтение почти не банится — предпочитай его. Сомневаешься в отправке — замедлись или спроси владельца.