Telegram MTProxy Notify для Home Assistant

Пользовательская интеграция для отправки уведомлений, фото, видео и файлов из HA через Telegram MTProto-прокси, когда api.telegram.org недоступен. Бот авторизуется по своему токену через MTProto. Прямого подключения к Bot API нет.

Возможности 0.3.1a1

Примеры фото с камеры, кнопок, команд и всех действий →

• Фото, видео, документы, голосовые сообщения, анимации, стикеры и альбомы.

• Inline-кнопки и клавиатуры, редактирование/удаление, реакции, опросы, координаты и живые черновики.

• События входящих команд, текста, вложений и нажатий кнопок; включаются отдельно в настройках.

• HTML/Markdown, тихая отправка, ответы, темы форумов и теги сообщений.

• Настройка через интерфейс Home Assistant на русском и английском.

• Ссылки https://t.me/proxy?... и tg://proxy?... с hex-секретами обычного, dd и ee Fake TLS формата.

• До пяти прокси по порядку. Если подключение не удалось, пробуется следующий.

• Стандартное действие notify.send_message, текст и необязательный заголовок.

• До 50 именованных получателей в одной записи интеграции; выбор одного или нескольких в автоматизации.

• Сохранение авторизации бота между перезапусками и изменение прокси через «Перенастроить».

• Соединения закрываются при выгрузке и остановке HA.

Статус: Alpha / Pre-release. Текстовые уведомления через MTProxy подтверждены пользователем на работающем HA. Новые медиа-действия и события проверены автоматическими тестами, но ещё требуют проверки с реальным ботом. Целевая версия — Home Assistant 2026.9.0+.

Установка через HACS

Интеграция устанавливается как пользовательский репозиторий и пока не включена в общий каталог HACS.

1. Откройте HACS → меню ⋮ → Пользовательские репозитории / Custom repositories.
2. Добавьте адрес https://github.com/IndeecDen/Telegram-MTProxy-Notify, выберите тип Integration.
3. Найдите Telegram MTProxy Notify и откройте карточку.
4. При необходимости включите отображение предварительных версий (Show beta versions) и выберите v0.3.1a1. Если альфа не отображается, можно выбрать ветку main.
5. Скачайте интеграцию и перезапустите Home Assistant.
6. Перейдите к настройке ниже.

Ручная установка

1. Скачайте telegram_mtproxy-0.3.1a1.zip из релиза и распакуйте в каталог конфигурации HA. Должен получиться путь:

   /config/custom_components/telegram_mtproxy/manifest.json
   

   При установке из исходников скопируйте туда папку custom_components/telegram_mtproxy целиком.
2. Перезапустите Home Assistant. При первом запуске HA устанавливает зависимости из PyPI; для этого нужен доступ к PyPI.

Настройка после установки

1. Откройте Настройки → Устройства и службы → Добавить интеграцию.
2. Найдите Telegram MTProxy Notify (в русской локализации — «Telegram через MTProxy»).
3. Заполните:
   • API ID / API hash: получите в my.telegram.org → API development tools. Это параметры приложения, а не токен бота. Они нужны и для ботов при работе по MTProto.
   • Токен бота: существующий токен от BotFather.
   • ID чата: числовой ID получателя из действующей настройки Telegram Bot в HA. Для личных уведомлений укажите свой ID и предварительно отправьте /start своему боту.
   • Ссылки прокси: вставьте от одной до пяти ссылок t.me/proxy, каждую на отдельной строке. Порядок определяет предпочтение. Прокси нужно получить самостоятельно, интеграция их не предоставляет.
4. Дождитесь проверки подключения. Сообщения во время настройки не отправляются. При двух недоступных прокси проверка может занять около 50 секунд.

При необходимости включите «Принимать команды и нажатия кнопок»; при обновлении опция остаётся выключенной.

Для замены прокси откройте меню записи интеграции и выберите Перенастроить / Reconfigure.

Несколько получателей

После обновления до v0.3.1a1 перезапустите HA и откройте Настройки → Устройства и службы → Telegram MTProxy Notify → ⋮ → Перенастроить.

Сохраните прежний основной ID чата. В поле «Дополнительные получатели» укажите пользователей, по одному в строке:

Анна: 123456789
Борис: 987654321

Каждый пользователь должен предварительно открыть этого бота и отправить /start. Нужен числовой ID чата, не @username. Поддерживается до 50 получателей вместе с основным. После сохранения для каждого появится отдельная сущность notify; её можно переименовать в HA, например в notify.telegram_anna.

В редакторе автоматизации выберите Telegram MTProxy Notify → Отправить сообщение / Отправить фото, затем в поле «Получатели» отметьте одного или нескольких пользователей. Для обычного текста также подходит стандартное действие Уведомления → Отправить сообщение с выбором нужных notify-сущностей.

action: telegram_mtproxy.send_message
data:
  entity_id:
    - notify.telegram_anna
    - notify.telegram_boris
  message: Дома обнаружено движение

Замените entity_id на реальные сущности из вашей установки. Для фото используйте тот же список entity_id в telegram_mtproxy.send_photo.

Можно выбирать по числовым ID из настроенного списка:

action: telegram_mtproxy.send_message
data:
  chat_id: [123456789, 987654321]
  message: Дома обнаружено движение

Если записей интеграции несколько, дополнительно укажите config_entry_id или используйте выбор сущностей.

Без явного выбора сообщение получает только прежний основной получатель. Добавление пользователей не превращает старые автоматизации в рассылку. Теги и last хранятся отдельно для каждого чата. В событиях входящих команд и кнопок chat_id указывает настоящий чат отправителя; при ответе передайте этот ID в действие.

Чтобы удалить дополнительного получателя, удалите его строку и сохраните настройки. Его notify-сущность будет удалена, отправка ему станет недоступной. Основную сущность и её ID обновление сохраняет. Если этот пользователь уже добавлен отдельной записью для того же бота, сначала уберите дублирующую запись и обновите затронутые автоматизации.

Фото по локальной ссылке камеры

Начиная с v0.3.1a1, url скачивается самим Home Assistant. Можно указать HTTP(S)-адрес камеры в локальной сети: HA получает снимок один раз и загружает его через MTProxy каждому выбранному получателю. К HA должен быть доступен этот URL без дополнительной авторизации.

action: telegram_mtproxy.send_photo
data:
  entity_id:
    - notify.telegram_anna
    - notify.telegram_boris
  url: "http://camera.local/cgi-bin/snapshot.sh?res=high&watermark=yes"

Предел загрузки — 50 MiB, общий таймаут — 60 секунд. Поле file и настройка allowlist_external_dirs для загрузки по URL не нужны. Если камера требует входа, используйте camera.snapshot и отправку локального файла.

Первое уведомление

Откройте Инструменты разработчика → Действия. Выберите notify.send_message и созданную сущность. Точный entity_id виден в карточке интеграции; значение ниже — пример:

action: notify.send_message
target:
  entity_id: notify.telegram_my_bot_123456789
data:
  title: Home Assistant
  message: Проверка уведомлений через MTProto-прокси

В существующих автоматизациях замените действие telegram_bot.send_message / старое notify.* на этот вызов, выбрав новую сущность. Получатель задан в настройках интеграции, параметр chat_id в действие передавать не нужно. Штатная интеграция Telegram Bot автоматически на этот транспорт не переключается.

Поведение при сбоях

• Прокси используется для всех соединений этого MTProto-клиента, включая смену дата-центра. При недоступности всех прокси возвращается ошибка; прямого обходного подключения нет.
• Успешный прокси используется первым при следующих подключениях.
• Если подтверждение отправки потеряно, сообщение не отправляется автоматически повторно: оно могло уже дойти. Следующее уведомление начнёт подключение со следующего прокси.
• Постоянной очереди сообщений нет. Ошибки видны в результате действия и трассировке автоматизации. После перезапуска незавершённые отправки не восстанавливаются.
• Токен, API hash, proxy secret и строка авторизации хранятся в конфигурации HA. Не публикуйте .storage или резервные копии с этими данными.

Ограничения

• t.me/webproxy пока не поддерживается. Эта ссылка использует отдельный WEB-транспорт; нельзя заменить в ней webproxy на proxy. Форма выдаст понятную ошибку.
• Текст — до 4096 UTF-16 единиц, подпись — до 1024, локальные файлы/альбомы — до 50 MiB. Поддерживаются plain_text, HTML и Markdown Telethon; MarkdownV2 не поддерживается.
• HTTP-авторизация URL и Bot API file_id не поддерживаются. Полный список отличий.
• Первичная цель — личный чат с ботом. Группы/каналы требуют прав бота и доступного Telegram access hash; разрешение таких получателей проверяется при настройке, но не гарантируется для любого числового ID.
• Проверка доступности сервера с компьютера разработчика не гарантирует его доступность из сети HA. Прокси могут перестать работать или сменить секрет.

Разработка и проверка

Python 3.12 или новее:

python -m venv .venv
# Активируйте окружение для своей ОС
python -m pip install -r requirements-dev.txt
python -m pytest -q -p no:cacheprovider
ruff check custom_components tests scripts
python -m compileall -q custom_components scripts

Тесты транспорта и клиента не требуют HA или реального бота. Проверяют разбор ссылок, Fake TLS HMAC, изоляцию состояний сессий, фрагментацию и EOF, закрытие сокета при ошибке, переключение прокси, отсутствие повторной отправки при неопределённом результате и отказ при неверной учётной записи. Это не заменяет проверку в работающем HA.

Проверка прокси из машины в той же сети, что и HA:

python scripts/probe_proxy.py

Скрипт запросит ссылку со скрытым вводом, установит Fake TLS и проверит зашифрованный MTProto ping. Токен бота и API ID для этого не требуются; Telegram-сообщения не отправляются. Строка авторизации этой проверки не сохраняется.

Сборка установочного архива:

python scripts/package.py

Техническая основа

• Авторизация ботов через MTProto.
• Telethon: авторизация и MTProxy.
• TelethonFakeTLS — формат ClientHello. Локальный адаптер изолирует состояние каждого соединения, использует системную случайность, проверяет HMAC ответа и добавляет ограничение времени и корректное закрытие потоков.
• Home Assistant NotifyEntity.

Зависимости закреплены в manifest.json, поскольку адаптер использует внутренний интерфейс транспорта Telethon. Перед обновлением зависимостей повторите тесты и проверку подключения.