Telegram-бот с API429: приватный текстовый ответ и офлайн-пример

Сначала скачайте оба файла и выполните офлайн-цикл

Нужны Python 3.10+ и POSIX-система, например macOS или Linux; сторонние пакеты не требуются. Скачайте api429-telegram-private-bot.py и api429-telegram-update-synthetic.json в одну папку, сохранив имена. Из этой папки выполните python3 -B api429-telegram-private-bot.py. Отсутствующий или повреждённый JSON останавливает пример. Флаг -B отключает запись байткода Python; он не включает сетевой режим.

Ожидаемый вывод: OFFLINE synthetic cycle: sent; network requests: 0. Данные сообщения, идентификаторы пользователя, бота и чата, каталог модели и ответы сервисов вымышлены. Пример прогоняет обработчик с подставным транспортом и временным локальным состоянием. Такая проверка показывает только локальную логику: она не отправляет inference, не подтверждает настоящий ответ модели и не проверяет работу реального Telegram-бота. Секреты окружения для этого режима не нужны.

Отдельный операторский запуск и точные параметры

Telegram не предоставляет поле OpenAI Base URL для подключения модели. Ваше приложение отдельно обращается к Telegram Bot API и отдельно отправляет Chat Completions в https://gateway.api429.com/v1. Для первого обычного текста выбран точный gemini-3.8-flash. Публичные OpenAPI и каталог описывают контракт и опубликованный ID; авторизованный GET /v1/models проверяет видимость модели для ключа, но не доказывает успешную генерацию.

Реальный режим предназначен только для владельца отдельного бота. До запуска проверьте, что этот бот нигде больше не обслуживается другим poller: на этой машине, другом сервере или в автоматизации. Локальная POSIX-блокировка защищает лишь общий каталог состояния на одной файловой системе и не является распределённой блокировкой. Не используйте пример параллельно с рабочим ботом.

Передайте TELEGRAM_BOT_TOKEN и API429_API_KEY через защищённое окружение операторской сессии: секретное хранилище может внедрить значения без вывода в журнал, либо оператор использует скрытый ввод read -s в Bash или getpass в Python. Не записывайте токены в команду, исходник, историю оболочки, репозиторий или снимки экрана. Задайте API429_MODEL=gemini-3.8-flash. Идентификаторы передаются именно флагами команды ниже; 123 и 456 — синтетические числа, их необходимо заменить своими проверенными ID. Каталог /private/bot-state — пример абсолютного приватного пути, который оператор выбирает под свою POSIX-среду.

Что проверяет один проход

Команда --execute-once выполняет один цикл, а не постоянный сервер или бесконечный опрос. Сначала getMe проверяет совпадение bot ID с --expected-bot-id. Затем getWebhookInfo должен вернуть пустой URL: активный либо неизвестный webhook останавливает запуск. Скрипт не вызывает deleteWebhook и не меняет конфигурацию существующего бота. Только после проверки каталога выполняется getUpdates с limit=1, timeout=0 и allowed_updates=["message"]. Последний параметр не гарантирует фильтрацию уже ожидающих обновлений.

Обработчик допускает только обычный недавний текст: приватный чат, точные --allowed-user-id и --allowed-chat-id, отправитель не бот, возраст сообщения не более 600 секунд и длина не более 4096 единиц UTF-16. Группы, каналы, изменённые сообщения, пересылки, бизнес-контекст и незнакомые поля не допускаются; неподходящее обновление пропускается, а неизвестная структура или неясный результат останавливает проход. Это намеренно узкая политика данного приложения, а не универсальная поддержка Telegram.

Для допустимого сообщения выполняется максимум одна попытка POST /v1/chat/completions с max_tokens=256 и stream=false, затем максимум одна попытка sendMessage с обычным текстом. Нет инструментов, повторов, разбиения ответа, parse_mode или потоковой выдачи. Слишком длинный, пустой либо незавершённый ответ приводит к остановке. max_tokens ограничивает выход одного запроса, но не общий расход: оплачиваемый вход и текущий тариф надо учитывать отдельно.

Состояние, неопределённость и смещение обновлений

Перед платной попыткой приложение сохраняет reserved, а перед отправкой ответа — send_pending. После подтверждённого результата записывает terminal. Если процесс остановился, ответ потерялся, запись завершилась неясно или сервис вернул неопределённый результат, последующие запуски останавливаются. Не удаляйте каталог состояния ради повтора: оператор должен отдельно сверить результат у обоих сервисов. Здесь обеспечивается политика at-most-once attempts в пределах сохранённого состояния: ответ может быть потерян. Обещания exactly-once доставки, криптографической защиты и гарантированной сохранности при потере питания не даются.

Положительный offset, равный предыдущему update_id плюс один, используется только для terminal младше 24 часов. После этого старое terminal-смещение опускается: Telegram хранит обновления не дольше суток, а после недели без новых обновлений следующий ID может быть выбран случайно. Пустой опрос не обновляет время terminal. Неопределённые reserved и send_pending не истекают никогда, отрицательный offset для сброса очереди не используется.

Транспорт ограничен фиксированными HTTPS-адресами Telegram и API429; перенаправления, прокси окружения и автоматические повторы отключены, ошибки выводятся без тел запросов и секретов. Эти ограничения принадлежат скачиваемому приложению. Они не являются обещаниями возможностей API429. При переходе к постоянной работе отдельно проектируйте наблюдение, бюджет и разбор зависшего состояния. Если удобнее визуальный сценарий, инструкции n8n и Make ниже описывают альтернативные реализации; они не импортируют этот Python-пример.

Два файла рядом: запуск по умолчанию без сети

python3 -B api429-telegram-private-bot.py
# OFFLINE synthetic cycle: sent; network requests: 0.

Только оператор: возможны расход и одно сообщение; замените синтетические ID

# TELEGRAM_BOT_TOKEN и API429_API_KEY уже внедрены защищённо в окружение.
export API429_MODEL=gemini-3.8-flash
python3 -B api429-telegram-private-bot.py --execute-once --expected-bot-id 123 --allowed-user-id 456 --allowed-chat-id 456 --state-dir /private/bot-state --dedicated-bot-no-other-poller

Оплата и тест $10

• Карта российского банка. Пополнение баланса в личном кабинете.
• Счёт для юрлиц. Безналичная оплата с закрывающими документами.
• USDT и TON. Пополнение криптовалютой.

Тест $10. Подпишитесь на наш Telegram-канал через бота — получите $10 на баланс для первых запросов. Получить $10 в боте