Недавно я открыл для себя такую вещь как Telegram Bot API — официальное приложение от авторов месcенджера, позволяющее запустить у себя локальный и полнофункциональный сервер API для ботов Телеграма. Фактически это копия api.telegram.org, но с некоторыми очень приятными дополнениями.
Началось все с того, что с начала 2026 года у меня стали возникать странные проблемы с отправкой фото и видео файлов из HA в Телеграм. В процессе поиска какого-либо решения я прямо на официальном сайте Телеграма наткнулся на описание некого Local Bot API Server, позволяющего получить следующие бенефиты:
- Скачивание файлов без ограничений по размеру.
- Загрузка файлов размером до 2000 МБ.
- Загрузка файлов с использованием локального пути и схемы file URI.
- Использование HTTP URL для вебхука.
- Использование любого локального IP-адреса для вебхука.
- Использование любого порта для вебхука.
- Установка значения max_webhook_connections до 100 000.
- Получение абсолютного локального пути в поле file_path без необходимости скачивать файл после запроса getFile.
Мне это показалось интересным и перспективным с точки зрения возможного решения проблемы с отправкой медиафайлов и я решил попробовать.
На тот момент в интеграции telegram_bot отсутствовала поддержка смены API Endpoint для бота, поэтому пришлось заняться перенаправлением api.telegram.org на локальный сервер с подменой SSL сертификата для этого адреса, настройкой доверия HA моему сертификату и прочими упражнениями. Это заняло время, но в итоге мне удалось заставить работать HA с моим собственным локальным сервером Bot API.
И самое главное — в моменте это решило проблему таймаутов при отправке медиафайлов!
Где-то в это же время был написан feature request на добавление в HA поддержки локального API, а маинтейнер интеграции очень оперативно эту поддержку добавил. Thank you @hanwg!
Итак, начиная с версии Home Assistant 2026.2 появилась поддержка смены API Endpoint для бота что позволило без особых проблем использовать локальное приложение Bot API.
Это подтолкнуло меня на дальнейшее изучение темы и привело к странному факту — официальная версия Telegram Bot API «из коробки» поддерживает работу с прокси-серверами, (в т.ч. MTProto-proxy за счет использования библиотеки tdlib), но при этом в нем напрочь отсутствует возможность простой их настройки. Все предлагается делать через редактирование кода с последующей компиляцией. А разработчики, судя по всему, менять ситуацию не намерены.
К моему счастью, т.к. я совсем не разработчик и о C++ имею крайне слабое представление, я нашел форк приложения с изменениями, позволяющими быстро и просто настраивать прокси-сервер с помощью параметров командной строки. После этого осталось дело за малым — адаптировать код к последним версиям Telegram Bot API и собрать на его основе приложение (Add-on) для Home Assistant.
Итак, мое первое приложение для Home Assistant: Telegram Bot API.
Основные преимущества, которые дает использование локального сервера Bot API:
- Увеличение лимитов
Вы сможете загружать файлы размером до 2 ГБ (стандартный API ограничен 50 МБ). - Webhooks без «белого» IP адреса
В обычном режиме для работы интеграции telegram_bot в режиме webhooks необходим доступ от серверов Телеграма до вашего HA с целым рядом ограничений. При использовании локального приложения все это не нужно.
Вы можете не открывать прямой доступ из интернета до вашего ХА, все соединения с серверами Телеграм являются исходящими. - Снижение задержек (Latency)
Весь сетевой трафик между HA и API остается внутри docker-сети HA OS, что ускоряет обработку запросов между HA и API-сервером. - Решение проблем доступности Telegram
Возможность работы через прокси позволяет боту сохранять связь с серверами Telegram, даже если прямой доступ к ним затруднен или отсутствует полностью. - Меньше «лишних» соединений
Поскольку Home Assistant общается с локальным приложением, а оно через прокси с серверами Telegram, внешние серверы видят только IP прокси-сервера, а не ваш реальный домашний адрес. - Единая экосистема
Установка в виде приложения (аддона) позволяет управлять сервером API прямо из интерфейса Home Assistant (обновления, бэкапы, логи). Возможность использовать локальное API для отправки сообщений, например, из ESPHome или bash скриптов.
Установка приложения в Home Assistant крайне проста и описана в репозитории.
А для тех, кто не хочет использовать именно приложения для HA, есть отдельный Docker образ с поддержкой прокси.
Актуальная документация по приложению расположена здесь, важные моменты на которые стоит обратить внимание:
- Возможные решения проблемы получения api_id и api_hash на https://my.telegram.org/apps.
- Ошибки супервизора и их обход при настройке приложения.
- Изменение URL Webhook’а на прямой (http://homeassistant:8123) в версиях HA <= 2026.3.
Сам я уже достаточно продолжительное время использую это решения для интеграции HA и Телеграма, и у меня только положительные впечатления. Так что, если вы испытываете те или иные проблемы с работой Телеграм в Home Assistant, попробуйте локальный сервер Telegram Bot API, возможно вам понравится. =)
Задать вопросы, указать на ошибки или предложить что-то вы всегда можете в разделах issues / discussions репозитория, а так же в группе Телеграм https://t.me/simple_ha.