Прокси API

Прозрачный прокси Telegram API с перехватом исходящих сообщений бота

BotMux предоставляет прокси Telegram API по адресу /tgapi/, который прозрачно пересылает запросы на api.telegram.org и перехватывает исходящие сообщения. Также прокси перехватывает ряд управляющих методов, чтобы ваш бэкенд мог использовать стандартный Telegram Bot API без конфликтов с внутренним состоянием BotMux.

​

Зачем использовать прокси API?

getUpdates в Telegram возвращает только входящие сообщения — сообщения, отправленные самим ботом, не включаются. Прокси API решает эту проблему, перехватывая методы отправки и сохраняя отправленное сообщение в базу данных.

​

Настройка

Измените базовый URL API в вашем бэкенде:

# До (напрямую)
https://api.telegram.org/bot{TOKEN}/sendMessage

# После (через прокси BotMux)
http://localhost:8080/tgapi/bot{TOKEN}/sendMessage

Прокси пересылает все запросы в Telegram и возвращает ответы без изменений, за исключением перехватываемых методов, которые BotMux обрабатывает внутренне.

​

Прокси загрузки файлов

BotMux также предоставляет эндпоинт загрузки файлов, совместимый как замена base_file_url для библиотек Telegram-ботов:

# По умолчанию (Telegram)
https://api.telegram.org/file/bot{TOKEN}/{file_path}

# Через прокси BotMux
http://localhost:8080/tgapi/file/bot{TOKEN}/{file_path}

Этот эндпоинт загружает файл из Telegram и передаёт его клиенту. Файлы WebP (стикеры) автоматически конвертируются в PNG для совместимости с браузерами.

​

Захватываемые методы отправки

Метод	Описание
sendMessage	Текстовые сообщения
sendPhoto	Фотографии
sendAudio	Аудиофайлы
sendDocument	Документы
sendVideo	Видео
sendAnimation	GIF/анимации
sendVoice	Голосовые сообщения
sendVideoNote	Видеозаметки
sendSticker	Стикеры
sendLocation	Местоположения
sendVenue	Места
sendContact	Контакты
sendPoll	Опросы
sendDice	Кубик
forwardMessage	Пересланные сообщения
copyMessage	Скопированные сообщения
editMessageText	Отредактированные текстовые сообщения
editMessageCaption	Отредактированные подписи
editMessageMedia	Отредактированные медиа

URL прокси API отображается в детальном просмотре бота, когда включён режим прокси (нажмите, чтобы скопировать).

​

Перехватываемые методы управления

Следующие методы Telegram Bot API перехватываются прокси и обрабатываются внутренне BotMux, а не пересылаются в Telegram:

Метод	Поведение
setWebhook	Регистрирует URL вебхука как URL бэкенда бота в BotMux и включает режим прокси. Авторегистрация неизвестных токенов требует переменной окружения BOTMUX_ALLOW_AUTO_REGISTER=1. URL вебхука должен использовать HTTPS (HTTP разрешён только для адресов обратной петли, если не установлен BOTMUX_STRICT_WEBHOOK=1). Поддерживает параметры url и drop_pending_updates.
deleteWebhook	Очищает URL бэкенда и отключает режим прокси для бота. Поддерживает drop_pending_updates.
getWebhookInfo	Возвращает внутреннее состояние вебхука BotMux, включая настроенный URL бэкенда и количество ожидающих обновлений.
getUpdates	Когда включён long polling, возвращает обновления из внутренней очереди BotMux вместо прямого опроса Telegram. Для любого другого бота, известного BotMux, возвращает пустой результат для предотвращения конфликтов.
logOut	Возвращает успех без пересылки в Telegram. Пересылка отключила бы токен на 10 минут, нарушая опрос BotMux.
close	Возвращает успех без пересылки в Telegram. Пересылка остановила бы экземпляр бота на стороне Telegram.

При установке BOTMUX_ALLOW_AUTO_REGISTER=1 перехват setWebhook позволяет миграцию без конфигурации: направьте ваш существующий бэкенд бота на URL прокси API BotMux, и BotMux автоматически зарегистрирует бота и начнёт пересылать обновления на ваш бэкенд.