Production MTProto user-бот на FastAPI + Telethon: WARP для обхода DPI и 5 граблей с Telegram

• Отправка и редактирование сообщений
  
• Обработка inline-кнопок и callback-запросов
  
• Управление существующими группами/каналами (если бот добавлен админом): banChatMember, unbanChatMember, pinChatMessage, setChatTitle
  
• Приём chat_join_request и approveChatJoinRequest / declineChatJoinRequest - то есть автоматический контроль входа по invite-link

• Создавать супергруппы. Совсем. Метода нет
  
• Добавлять юзеров в группу. Бот не может никого «затащить» внутрь - только принимать заявки от тех, кто пришёл по invite-link
  
• Резолвить @username ↔ user_id. Никак
  
• Стартовать диалог с юзером первым (нужен /start от юзера)

• Создание супергруппы (только MTProto)
  
• Добавление участников по @username из карточки Planfix (только MTProto)
  
• Resolve id ↔ @username (только MTProto)

┌──────────────────────────────────────┐
   │      Planfix (event source)          │
   └────────────────┬─────────────────────┘
                    │ webhook
                    ▼
   ┌──────────────────────────────────────┐
   │   n8n (orchestrator, 56 нод)         │
   └────────────────┬─────────────────────┘
                    │ HTTP + X-API-Key
                    ▼
   ┌──────────────────────────────────────┐
   │  FastAPI service (mtproto-api)       │
   │  ├─ Singleton TelegramClient         │
   │  ├─ /create-group  /add-users        │
   │  │  /resolve-user  /health           │
   │  └─ keepalive 180s + ensure_connected│
   └────────────────┬─────────────────────┘
                    │ MTProto
                    ▼
   ┌──────────────────────────────────────┐
   │  Cloudflare WARP (SOCKS5 :40000)     │
   │  обход РКН-DPI                       │
   └────────────────┬─────────────────────┘
                    ▼
   ┌──────────────────────────────────────┐
   │       Telegram MTProto API           │
   └──────────────────────────────────────┘

POST /create-group
X-API-Key: <secret>
Content-Type: application/json
{
  "title": "Проект Объект-42 Москва",
  "description": "Команда проекта",
  "admins": ["@admin_username"],
  "users": ["@team_member1", "@team_member2"],
  "request_approval": true
}

{
  "status": "ok",
  "chat_id": -1001234567890,
  "invite_link": "https://t.me/+abc...",
  "bot_added": true,
  "admins_added": ["admin_username"],
  "admins_errors": {},
  "users_added": ["team_member1"],
  "users_errors": {"team_member2": "user_privacy_restricted"}
}

ConnectionError: Connection to Telegram failed 5 time(s)

• Альтернативные DC (datacenters Telegram) - блокируются одинаково
  
• Все варианты connection в Telethon (ConnectionTcpFull, ConnectionTcpIntermediate, ConnectionTcpAbridged, ConnectionTcpObfuscated) - результат тот же

• WARP - VPN-клиент Cloudflare, есть консольная версия warp-cli под Linux. Бесплатный
  
• После warp-cli connect - весь исходящий трафик с VPS идёт через CF-сеть. Внешний IP меняется на CF Moscow (DPI его не видит, потому что трафик зашифрован между VPS и CF и снаружи выглядит как обычный HTTPS на CF)
  
• Telethon настраивается на использование SOCKS5 через локальный порт 40000 (стандартный WARP SOCKS-режим)

from telethon import TelegramClient
from telethon.network.connection import ConnectionTcpFull
import socks
PROXY = (socks.SOCKS5, "127.0.0.1", 40000)
client = TelegramClient(
    "session",
    API_ID,
    API_HASH,
    connection=ConnectionTcpFull,
    proxy=PROXY,
)

warp-cli status        # ожидается: Connected
curl --socks5 127.0.0.1:40000 -m 10 https://ipinfo.io/
# должен вернуть IP в формате Cloudflare Moscow

[Unit]
Description=MTProto FastAPI service
After=network-online.target warp-svc.service
Requires=warp-svc.service
[Service]
ExecStart=/opt/mtproto-api/venv/bin/uvicorn app:app --host 127.0.0.1 --port 8080
Restart=on-failure

from contextlib import asynccontextmanager
from fastapi import FastAPI
from telethon import TelegramClient
@asynccontextmanager
async def lifespan(app: FastAPI):
    # startup
    app.state.client = TelegramClient(
        SESSION, API_ID, API_HASH,
        connection=ConnectionTcpFull,
        proxy=(socks.SOCKS5, "127.0.0.1", 40000),
    )
    await app.state.client.start()
    # warmup entity cache
    async for _ in app.state.client.iter_dialogs(limit=300):
        pass
    # background keepalive
    app.state.keepalive_task = asyncio.create_task(_keepalive(app.state.client))
    yield
    # shutdown
    app.state.keepalive_task.cancel()
    await app.state.client.disconnect()
app = FastAPI(lifespan=lifespan)

• systemctl stop mtproto-api
  
• pgrep -af telethon - убедиться что параллельных процессов нет
  
• Атомарный reauth-скрипт через systemd-run --user --scope (не nohup/tmux через SSH, иначе скрипт умрёт при разрыве SSH-сессии и аккаунт зависнет в полу-авторизованном состоянии)
  
• Получаем новый session-string. Важно: запускать с того же IP что и production (тот же WARP), иначе Telegram security ставит флаг «вход с нового IP» и не даёт восстановить через SMS

• При создании группы сразу добавлять всех начальных участников (большая часть пройдёт)
  
• Для каждого, кто вернулся в users_errors - сразу отправлять invite-link через бота в личку
  
• Для всех новых членов через дни/недели после создания - использовать только invite-link + автоодобрение через Bot API при chat_join_request event

• При удалении специалиста из проекта - banChatMember через Bot API (или kickChatMember, что для супергрупп то же самое - юзер уходит в banned list)
  
• При возврате специалиста в проект - сначала unbanChatMember (вывести из banned list), затем сформировать персональный invite-link с request_approval=true и отправить юзеру в личку через бота
  
• Когда юзер кликает на invite-link, Telegram присылает chat_join_request на webhook
  
• Bot API workflow проверяет: есть ли его user_id в списке участников этого проекта в нашей DataTable? Если есть - approveChatJoinRequest, если нет - declineChatJoinRequest

• Сначала прогнать через /resolve-user с deep_search=true - итерируем участников всех групп где сессия есть, ищем нужный id
  
• Добавлять через invite-link (без необходимости в access_hash, юзер сам кликнет)

• asyncio.Lock в FastAPI сериализует все Telegram-вызовы → один Telethon-запрос за раз внутри сервиса, никаких параллельных API-вызовов
  
• В n8n между batch-операциями ставлю Wait 3-10 секунд с jitter (хотя в реальной нагрузке между задачами Planfix проходят минуты)
  
• На уровне endpoint - retry x2 при ConnectionError
  
• При FloodWaitError от Telethon - читаем e.seconds, ждём seconds + 5, делаем один повтор; если упало повторно - возвращаем 429 в HTTP-ответ с тем же seconds в payload, дальше уже n8n решает что делать

async def ensure_connected(client: TelegramClient):
    if not client.is_connected():
        await client.connect()
    # дополнительный health-check
    try:
        await asyncio.wait_for(client.get_me(), timeout=3)
    except (asyncio.TimeoutError, ConnectionError):
        await client.disconnect()
        await client.connect()

• Один client per session - строго (разбирал выше)
  
• Не коммитить .env с MTPROTO_SESSION в git. Никогда. Session-string даёт полный доступ к аккаунту, эквивалентен паролю
  
• Не логировать тело запросов - содержит user_id, который в связке с @username может раскрыть приватные данные
  
• CORS не настраивать - сервис вызывается только server-side из n8n, фронтенд туда не ходит
  
• systemd-run для интерактивных операций, особенно reauth - nohup и tmux через SSH ненадёжны при разрыве SSH-сессии, скрипт умирает на середине, аккаунт остаётся в полу-авторизованном состоянии

• Singleton-клиент на сервис (не нарушать)
  
• WARP SOCKS5 для обхода DPI с РФ-VPS
  
• Mutual contact и льготный период - спроектировать архитектуру под это
  
• Opt-out юзера - fallback на invite-link с автоодобрением
  
• @username всегда лучше чем numeric id
  
• Keepalive + ensure_connected + warmup - паттерны без которых стабильности не будет

• Telethon docs - главный источник по MTProto в Python
  
• Telegram API docs (MTProto methods) - справочник методов
  
• Cloudflare WARP CLI - установка на Linux
  
• Cloudflare Tunnel - публикация сервиса без открытых портов
  
• FastAPI lifespan - Singleton-pattern для долгоживущих клиентов