> ## Documentation Index
> Fetch the complete documentation index at: https://docs.botmux.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Прокси 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.                                                                                                                                                                                                                                                                         |

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