Недавно я открыл для себя такую вещь как 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.
Мне это показалось интересным и перспективным с точки зрения возможного решения проблемы с отправкой медиафайлов и я решил попробовать. Собрал и запустил отдельный контейнер рядом с HA без особых проблем.
К сожалению, на тот момент в интеграции telegram_bot отсутствовала поддержка смены API Endpoint для бота, поэтому пришлось заняться перенаправлением api.telegram.org на локальный сервер. С подменой SSL сертификата для этого адреса, настройкой доверия HA моему сертификату и прочими упражнениями. Это заняло время, но в итоге мне удалось заставить работать HA с моим собственным локальным сервером Bot API.
И самое главное — в моменте это решило проблему таймаутов при отправке медиафайлов! Автоматизации отрабатывали, файлы отправлялись. Хоть и с видимыми задержками. Впрочем такое поведение, по понятным причинам, было во всех клиентах.
Где-то в это же время был написан feature request на добавление в HA поддержки локального API, а маинтейнер интеграции telegram_bot очень оперативно эту поддержку добавил. 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-сервером. К примеру, в условиях «замедленного» доступа к серверам Телеграма, локальное API убирает ошибки отправки (таймауты) медиафайлов в автоматизациях HA. - Решение проблем доступности Telegram
Возможность работы через прокси позволяет боту сохранять связь с серверами Telegram, даже если прямой доступ к ним затруднен или отсутствует полностью. А использование стандартной библиотеки tdlib позволяет подключать бота через MTProto-прокси. Т.е. использовать один и тот же прокси для клиента на телефоне\ПК и бота HA. - Меньше «лишних» соединений
Поскольку Home Assistant общается только с локальным приложением, а оно для подключения к серверам Telegram может использовать прокси, то в этом случае внешним серверам доступен только IP адрес прокси-сервера, а не ваш реальный домашний IP. - Единая экосистема
Установка в виде приложения (аддона) позволяет управлять сервером API прямо из интерфейса Home Assistant: настройка, обновление, бэкапы, логи, просмотр статистики.
Возможность использовать локальное API для отправки сообщений, например, из ESPHome или bash скриптов.
Установка приложения в Home Assistant крайне проста и описана в репозитории.
А для тех, кто не хочет или не может использовать именно приложения (add-on) для HA, есть отдельный Docker image с добавленной поддержкой прокси и docker-compose.yaml.
Актуальная документация по приложению расположена здесь, важные моменты на которые стоит обратить внимание:
- Возможные решения проблемы получения 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 репозитория, а так же в группе Телеграм.