====== Настройка интеграции Matrix в Home Assistant ======

<note warning>
**Важное предупреждение:** Вы указали пароль в открытом виде. Никогда не делитесь паролями в чатах! Рекомендуется:
  * Сменить пароль для аккаунта @ha:chat.2admina.ru
  * Использовать ''!secret'' для хранения чувствительных данных
</note>

===== 📋 Шаг 1: Подготовка secrets.yaml =====
Создайте или отредактируйте файл ''/config/secrets.yaml'':

<code yaml>
# Добавьте сюда ваши данные
matrix_homeserver: "https://chat.2admina.ru"
matrix_username: "@ha:chat.2admina.ru"
matrix_password: "********"  # ⚠️ замените на новый пароль!
matrix_room: "#ваша_комната:chat.2admina.ru"
</code>

===== ⚙️ Шаг 2: Настройка configuration.yaml =====
Добавьте в ''/config/configuration.yaml'':

<code yaml>
# Основная интеграция Matrix
matrix:
  homeserver: !secret matrix_homeserver
  username: !secret matrix_username
  password: !secret matrix_password
  verify_ssl: true  # если у вас самоподписанный сертификат, установите false
  rooms:
    - !secret matrix_room  # комнаты для прослушивания команд
  commands:  # опционально: команды для обработки
    - word: статус
      name: ha_status
    - word: перезагрузка
      name: ha_restart

# Платформа уведомлений
notify:
  - name: matrix_notify
    platform: matrix
    default_room: !secret matrix_room
</code>

===== 🔄 Шаг 3: Перезагрузка Home Assistant =====
  * Перейдите в **Настройки** → **Система** → **Перезагрузка**
  * Нажмите **Перезагрузить конфигурацию** (или перезапустите весь сервер)

После перезагрузки интеграция появится в **Настройки** → **Устройства и службы**.

===== 📬 Использование уведомлений =====
В автоматизациях:
<code yaml>
automation:
  - alias: "Уведомление в Matrix при срабатывании датчика"
    triggers:
      - trigger: state
        entity_id: binary_sensor.motion_door
        to: "on"
    actions:
      - action: notify.matrix_notify
        data:
          message: "🚪 Движение у входной двери!"
          
            format: "html"  # опционально: поддержка базового HTML
</code>

Отправка изображения:
<code yaml>
action: notify.matrix_notify
data:
  message: "📷 Снимок с камеры"
  
    images:
      - /config/www/camera/snapshot.jpg
</code>

<note>
⚠️ Для отправки файлов из внешних папок добавьте в ''configuration.yaml'':
<code yaml>
homeassistant:
  allowlist_external_dirs:
    - /config/www/camera
</code>
</note>

===== 🎯 Обработка команд из Matrix =====
Создайте автоматизацию для реакции на команды:
<code yaml>
automation:
  - alias: "Обработка команды !статус"
    triggers:
      - trigger: event
        event_type: matrix_command
        event_data:
          command: ha_status
    actions:
      - action: notify.matrix_notify
        
          message: "✅ Home Assistant работает нормально. Версия: {{ states('sensor.home_assistant_version') }}"
</code>

===== 🔐 Рекомендации по безопасности =====
  * Используйте **отдельный аккаунт** для бота, не ваш личный.
  * **Ограничьте права бота**: не давайте права администратора в комнатах.
  * **Проверьте SSL**: если сервер использует самоподписанный сертификат, установите ''verify_ssl: false'' (менее безопасно).
  * Регулярно меняйте пароль и обновляйте ''secrets.yaml''.

===== 🛠️ Альтернатива: кастомная интеграция =====
Если официальная интеграция не поддерживает все нужные функции (E2EE, медиа), можно рассмотреть [[https://home-assistant.io|Matrix Chat custom component]]:

<code yaml>
# После установки в /config/custom_components/
matrix_chat:
  homeserver: !secret matrix_homeserver
  user_id: !secret matrix_username
  access_token: !secret matrix_access_token  # токен вместо пароля
  verify_ssl: true
</code>
Токен доступа можно получить в клиенте Element: **Настройки** → **Помощь и информация** → **Токен доступа**.

===== ❓ Устранение неполадок =====

^ Проблема ^ Решение ^

| Не подключается к серверу | Проверьте verify_ssl, URL homeserver |
| Не видит команды | Убедитесь, что бот добавлен в комнату и комнаты указаны в конфиге |
| Ошибка аутентификации | Проверьте логин/пароль, возможно сервер требует токен |
| Не отправляет уведомления | Проверьте, что default_room существует и бот в нём состоит |

**Логи интеграции:** Настройки → Система → Журналы → Фильтр: ''homeassistant.components.matrix''

Нужна помощь с конкретной ошибкой? Пришлите лог — помогу разобраться! 🤖✨