Telegram

Telegram

Введение

Telegram — это плагин BARY для управления умным домом и получения уведомлений через Telegram-бота.

После настройки пользователь может отправлять боту текстовые команды, голосовые сообщения, открывать меню умного дома и получать уведомления о важных событиях. Например, через Telegram можно включить свет, проверить состояние дома, открыть список камер или получить сообщение о проблемном устройстве.

Плагин не добавляет устройства самостоятельно. Он использует устройства, комнаты, камеры, уведомления и ассистента, которые уже настроены в BARY.

Что умеет плагин

Telegram-плагин поддерживает несколько основных сценариев:

• отправка текстовых команд в BARY AI Assistant;
• отправка голосовых сообщений ассистенту;
• главное меню умного дома в Telegram;
• просмотр состояния дома;
• просмотр устройств, которые требуют внимания;
• управление устройствами по комнатам;
• просмотр камер и сохранение кадров;
• получение уведомлений от BARY.

Набор доступных действий зависит от того, какие устройства и модули уже добавлены в BARY.

Что подготовить

Перед настройкой подготовьте:

• Telegram-бота, созданного через BotFather;
• токен бота;
• Telegram user id пользователей, которым разрешён доступ;
• установленный и настроенный BARY AI Assistant, если нужны текстовые и голосовые команды ассистенту;
• ffmpeg на сервере BARY, если нужны голосовые сообщения.

Для получения уведомлений дополнительных действий в Telegram обычно не требуется: плагин рассылает уведомления разрешённым пользователям.

Как создать Telegram-бота

Создайте бота в Telegram через BotFather:

1. Откройте Telegram.
2. Найдите пользователя @BotFather.
3. Отправьте команду /newbot.
4. Укажите название бота.
5. Укажите username бота. Он должен заканчиваться на bot, например my_bary_bot.
6. Скопируйте выданный BotFather токен.

Токен понадобится в настройках плагина BARY.

Как установить

Telegram-плагин устанавливается из стандартного каталога модулей BARY.

Сначала убедитесь, что плагин установлен в системе:

1. Откройте Настройки.
2. Перейдите в раздел Обновления.
3. Найдите модуль Telegram.
4. Если модуль не установлен, поставьте рядом с ним галочку.
5. Нажмите Сохранить внизу страницы.

После этого добавьте плагин в BARY:

1. Откройте Настройки.
2. Перейдите в раздел Устройства.
3. Нажмите Добавить.
4. В каталоге поддерживаемых устройств выберите Telegram.
5. Укажите комнату, в которой будет отображаться плагин.
6. Заполните настройки.
7. Сохраните устройство.

После сохранения плагин подключится к Telegram-боту и начнёт принимать сообщения от разрешённых пользователей.

Настройки плагина

Доступ пользователей

Telegram-плагин работает только с пользователями, которые указаны в настройке Allowed Telegram user ids.

Если пользователь не добавлен в список, бот не будет выполнять его команды. Вместо этого он ответит:

Доступ не настроен.
Ваш Telegram user id: ...

Этот id можно скопировать и добавить в настройку Allowed Telegram user ids.

Если список разрешённых пользователей пустой, доступ не получит никто. Это защищает управление домом от случайных пользователей, которые могут найти username бота.

Команды в Telegram

Плагин поддерживает две служебные команды:

В личном чате с ботом можно отправлять обычные текстовые команды без служебной команды /menu. Например:

включи свет на кухне
выключи кондиционер
какая температура в спальне

В групповых чатах плагин обрабатывает свободный текст только при упоминании бота по username. Например:

@my_bary_bot включи свет на кухне

Это нужно, чтобы бот не реагировал на все сообщения в группе.

Текстовые команды ассистенту

Текстовые команды передаются в BARY AI Assistant. Telegram-плагин сам не распознаёт смысл команды: он отправляет текст ассистенту и возвращает пользователю результат.

Примеры команд:

включи свет на кухне
выключи свет в коридоре
открой шторы в спальне
поставь яркость 50 процентов
какая температура в гостиной

Если ассистент выполнил команду, бот покажет короткое подтверждение. Если команда не распознана или не может быть выполнена, бот сообщит об ошибке.

В некоторых ответах бот может показать кнопки с обратными действиями. Например, после включения света может появиться кнопка для выключения этого же устройства.

Голосовые сообщения

В личном чате с ботом можно отправлять голосовые сообщения. Плагин передаёт аудио в BARY AI Assistant, а затем отправляет в Telegram результат выполнения команды.

Голосовые сообщения работают только при выполнении условий:

• пользователь добавлен в Allowed Telegram user ids;
• сообщение отправлено в личный чат с ботом;
• в BARY есть доступный BARY AI Assistant;
• на сервере установлен ffmpeg.

Если ffmpeg не установлен, бот ответит:

Голосовые недоступны: не найден ffmpeg.

Если ассистент не найден, бот ответит:

Ассистент не найден.

Главное меню умного дома

Команда /menu открывает главное меню умного дома.

В меню доступны разделы:

Внутри меню используются кнопки Telegram. Можно переходить между разделами, обновлять данные и возвращаться назад.

Управление по комнатам

Раздел Управление по комнатам показывает комнаты из BARY. После выбора комнаты бот показывает устройства этой комнаты и доступные действия.

Обычно через меню можно:

• включать и выключать устройства;
• менять поддерживаемые режимы;
• выполнять действия, которые доступны для конкретного устройства в BARY.

Если у устройства нет подходящих действий, оно может не отображаться в меню управления или отображаться без кнопок действия.

Состояние дома

Раздел Состояние дома показывает текущую сводку по дому. Он полезен, когда нужно быстро проверить систему из Telegram без открытия интерфейса BARY.

Данные в этом разделе можно обновить кнопкой Обновить.

Состав сводки зависит от устройств и модулей, которые установлены в BARY.

Требует внимания

Раздел Требует внимания собирает устройства и состояния, которые могут требовать реакции пользователя.

Например, в этом разделе могут отображаться устройства с проблемами связи, ошибками, тревожными состояниями или другими важными статусами, если такие данные доступны в BARY.

Данные в этом разделе можно обновить кнопкой Обновить.

Камеры

Раздел Камеры показывает камеры, добавленные в BARY.

Для камеры можно открыть текущий кадр. В окне просмотра доступны действия:

• Обновить кадр — получить новый кадр с камеры;
• Сохранить кадр — отправить текущий кадр отдельным сообщением;
• К списку камер — вернуться к списку камер.

Если BARY не смог получить изображение с камеры, бот покажет сообщение, что превью недоступно.

Уведомления

Telegram-плагин может отправлять пользователям уведомления от BARY.

Поддерживаются разные типы уведомлений:

• обычные уведомления с заголовком и текстом;
• события устройств;
• массовые события устройств, например потеря или восстановление соединения;
• рекомендации и сообщения аналитики;
• события Frigate или зон видеонаблюдения, если они приходят от соответствующего модуля.

Уведомления отправляются всем пользователям из Allowed Telegram user ids.

Для некоторых событий плагин форматирует сообщение в более удобный вид. Например, события устройств могут показываться с комнатой и названием устройства, а события камер могут приходить вместе с изображением.

Использование в группах

Бота можно добавить в Telegram-группу, но свободные текстовые команды в группе обрабатываются только при упоминании username бота.

Пример:

@my_bary_bot выключи свет в гостиной

Голосовые сообщения в группах не обрабатываются. Для голосового управления используйте личный чат с ботом.

Ограничения

При использовании плагина учитывайте ограничения:

• команды выполняются только для пользователей из Allowed Telegram user ids;
• текстовые и голосовые команды требуют доступного BARY AI Assistant;
• голосовые сообщения работают только в личном чате;
• для голосовых сообщений на сервере нужен ffmpeg;
• в групповых чатах нужно упоминать username бота;
• меню показывает только те комнаты, устройства и действия, которые доступны в BARY;
• качество выполнения команд зависит от настроек ассистента и от того, как устройства описаны в BARY.

Если что-то не работает