В большинстве туториалов по Telegram-ботам всё начинается с одного куска кода: получили токен у @BotFather, поставили python-telegram-bot или aiogram, написали хендлер, deploy. Это Bot API. И в 90% задач этого хватает.

А потом приходит задача которую Bot API не закрывает в принципе: программно создать супергруппу под конкретный проект и добавить туда нужных людей по @username, и сделать это десятки раз в день. Bot API такое не умеет даже теоретически - метода «создать группу» там нет, метода «добавить юзера в группу» тоже. Лезете в полную документацию Telegram API искать обход, упираетесь в раздел  channels.createChannel  /  channels.inviteToChannel под MTProto, и начинается совсем другая история - не Bot API, а user-бот через telethon.

В этой статье разбираю как мы сделали production MTProto user-бот на FastAPI + Telethon. Под капотом: Cloudflare WARP для обхода DPI (без него с российского VPS просто не подключиться), Singleton-клиент с keepalive, in-memory cache resolve-юзеров, и 5 ограничений Telegram которые знают только те кто лез туда ногами. Реальный production-сервис у клиента в нише строительства/монтажа, обслуживает связку Planfix → Telegram-группы под каждый проект.

Сервис написан на Python 3.11. Стек: Telethon 1.43.2, FastAPI 0.136.1, Uvicorn 0.46.0, Pydantic 2.13.4. На VPS под systemd, наружу через Cloudflare Tunnel. Вызывается из n8n через HTTP-ноду.

n8n запускается одной командой docker run и через пять минут вы видите логин-форму. Это маркетинговый ролик. Реальный production-конфиг - с persistent storage, корректными webhook-URL, ретраями, бэкапами PostgreSQL и мониторингом - выглядит сильно иначе. В этой статье - конфигурация, которую я держу на 12 проектах в течение полутора лет. Плюс три грабли, на которые наступал лично.

Все примеры - community-edition, без коммерческой лицензии. На проде у меня сейчас крутится 2.19.5, но в image: стоит n8nio/n8n:latest плюс Watchtower (про него ниже) - он подтягивает свежий образ ночью. Внутри 2.x API/env-переменные стабильны, рекомендую :latest + Watchtower на проектах где простой 5 минут утром не критичен, и закреплённый минор (:2.19.5) - на проектах где даунтайм нельзя.

Хочу рассказать про баг, который я искал полтора дня и который оказался опечаткой длиной в одну инструкцию. Если коротко: PostgreSQL (16.4 в моём случае, но воспроизводится начиная с 12-й) не разрешает UNION ALL сразу после ORDER BY ... LIMIT N без круглых скобок. И самое неприятное - ошибку об этом я узнал последним, потому что между моим SQL-запросом и логами стояло пять промежуточных слоёв, каждый из которых её по-своему проглотил.

Расскажу как нашёл, как фиксил, и что в итоге добавил в pre-deploy чек-лист.

Понадобилась мне семантика - не в смысле «один раз глянуть Wordstat в браузере», а программно, чтобы прогонять по 50-100 фраз в день и складывать результаты в свою базу. Контекст: веду контент-маркетинг для агентства разработки чат-ботов BotKraft, статьи под Яндекс Нейро. Веб-Wordstat для такого объёма не вариант - копировать вручную из таблички полдня. Direct API - слишком дорогой вход: нужен рекламный аккаунт, отдельный OAuth, у меня этого не было и заводить ради одного метода не хотелось.

Случайно полез в новые сервисы Yandex Cloud AI Studio (там сейчас живёт YandexGPT) и обнаружил, что Wordstat теперь есть в Search API v2 - отдельным сервисом без зависимости от Direct. Доступ - обычный API-ключ из AI Studio, тот же что и для YandexGPT. По сути в один клик получаешь ещё и доступ к семантике.

Подключал, по дороге собрал коллекцию граблей. Этим и поделюсь.