Прокси 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 для совместимости с браузерами.

Local Bot API Server как upstream

BotMux может использовать self-hosted Telegram Bot API Server вместо api.telegram.org:

./botmux -tg-api http://127.0.0.1:8081
# или
TELEGRAM_API_URL=http://127.0.0.1:8081 ./botmux

В режиме --local upstream getFile может возвращать абсолютные пути в файловой системе. BotMux обрабатывает это так:

Через /tgapi/ — ответы getFile переписывают абсолютный file_path в относительный путь для BotMux, чтобы бэкенды могли использовать base_file_url=http://botmux:8080/tgapi.
Прямое чтение с диска — если BotMux и Local Bot API на одном хосте/томе, укажите корень файлов:

./botmux -tg-api http://127.0.0.1:8081 -tg-api-files /var/lib/telegram-bot-api
# или
TELEGRAM_API_FILES=/var/lib/telegram-bot-api ./botmux

С -tg-api-files эндпоинты /api/media и /tgapi/file/ могут отдавать файлы напрямую с диска. При кастомном -tg-api автоматически включаются увеличенные лимиты загрузки (до ~2 ГБ) и таймауты.

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

Метод	Описание
`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 автоматически зарегистрирует бота и начнёт пересылать обновления на ваш бэкенд.

Начало работы

Основные концепции

Функции

Маршрутизация

Мосты

Аутентификация

Конфигурация

Архитектура

Развертывание

Прокси API

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

Настройка

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

Local Bot API Server как upstream

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

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

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

​Настройка

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

​Local Bot API Server как upstream

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

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

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

Настройка

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

Local Bot API Server как upstream

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

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