Matrix-Server/README.md

Matrix Messenger for Home Assistant

Send messages from Home Assistant to Matrix rooms — including encrypted rooms (E2EE). Ask questions and react to text replies or emoji reactions in automations.

---

Features

• Send messages to one or more Matrix rooms via service call or notify.* entity
• Ask questions — send a question to a room and wait for a reply (text or emoji reaction)
• E2EE support — end-to-end encrypted rooms via matrix-nio
• Two auth methods — username + password, or access token
• Fully GUI-configurable — no YAML required, all settings via the HA config flow
• HACS-installable

---

Requirements

Requirement	Details
Home Assistant	≥ 2026.4.0
Python package	matrix-nio[e2e] >= 0.21.0 (installed automatically)
Native library	libolm — pre-installed in HA OS, Supervised, and Container

Note for HA Core (venv) installations: libolm must be installed manually on the host system (apt install libolm-dev on Debian/Ubuntu).

---

Installation

Via HACS (recommended)

1. Open HACS → Integrations → ⋮ → Custom repositories
2. Add your Gitea repository URL, category: Integration
3. Search for Matrix Messenger and install
4. Restart Home Assistant

Manual

1. Copy the custom_components/matrix_messenger/ folder into your HA config directory
2. Restart Home Assistant

---

Configuration

Go to Settings → Devices & Services → Add Integration and search for Matrix Messenger.

Step 1 — Matrix Server

Field	Example
Homeserver URL	https://matrix.org
Authentication method	Username + Password or Access Token

Step 2a — Username + Password

Field	Notes
Matrix User ID	@youruser:matrix.org
Password	Your Matrix account password
Device name	Shown in your Matrix client's session list (optional)

Step 2b — Access Token

Retrieve your token in your Matrix client: Settings → Security → Sessions → Show access token.

Field	Notes
Matrix User ID	@youruser:matrix.org
Access Token	Paste the token here; the device ID is fetched automatically

Step 3 — Room Selection

All rooms the account has joined are listed. Select one or more rooms.

Enable background sync — when enabled, the integration polls Matrix every 5 seconds continuously. Required if you want to receive replies to questions without triggering ask_question first.

---

Reconfiguring rooms

Go to Settings → Devices & Services → Matrix Messenger → Configure to change the selected rooms or toggle background sync at any time.

---

Services / Actions

matrix_messenger.send_message

Sends a plain-text message to a room.

Parameter	Type	Required	Description
room_id	string	✓	Matrix room ID, e.g. !abc123:matrix.org
message	string	✓	Message text

Example:

action: matrix_messenger.send_message
data:
  room_id: "!abc123:matrix.org"
  message: "Front door opened."

---

matrix_messenger.ask_question

Sends a question to a room and waits for a reply. Once a matching reply arrives, the event matrix_messenger_response is fired. After the timeout (default 30 min) the question expires silently.

Parameter	Type	Required	Default	Description
room_id	string	✓	—	Matrix room ID
question	string	✓	—	Question text
options	list of strings		[]	If set, only these exact replies (or emoji reactions) are accepted
timeout	integer (seconds)		1800	How long to wait. Min 60, max 7200

Example — free-text reply:

action: matrix_messenger.ask_question
data:
  room_id: "!abc123:matrix.org"
  question: "Should I water the plants?"

Example — constrained options:

action: matrix_messenger.ask_question
data:
  room_id: "!abc123:matrix.org"
  question: "Alarm triggered — is this a false alarm?"
  options:
    - "Yes"
    - "No"
  timeout: 300

The integration appends the options to the message:

Alarm triggered — is this a false alarm?

Mögliche Antworten: Yes / No

---

Notify entities

Each configured room also creates a notify.* entity:

notify.matrix_<room display name>

These appear in the HA notification UI and can be used anywhere a notify target is accepted.

Example:

action: notify.matrix_wohnzimmer
data:
  title: "Waschmaschine"
  message: "Programm beendet."

The title is prepended in bold: Waschmaschine\nProgramm beendet.

---

Events

matrix_messenger_response

Fired when a reply to an ask_question call is received.

Attribute	Type	Description
question_id	string (UUID)	Unique ID of the question (from the service call)
room_id	string	Matrix room ID where the reply was received
response	string	The reply text or emoji
response_type	"text" or "emoji"	How the reply was sent
sender	string	Matrix user ID of the person who replied

---

Automation examples

Send a notification when motion is detected

automation:
  trigger:
    - platform: state
      entity_id: binary_sensor.front_door_motion
      to: "on"
  action:
    - action: matrix_messenger.send_message
      data:
        room_id: "!abc123:matrix.org"
        message: "Motion detected at the front door."

---

Ask a question and branch based on the answer

automation:
  alias: "Alarm confirmation"
  trigger:
    - platform: state
      entity_id: alarm_control_panel.home
      to: "triggered"
  action:
    # 1. Send the question — store question_id for matching
    - action: matrix_messenger.ask_question
      data:
        room_id: "!abc123:matrix.org"
        question: "Alarm triggered! False alarm?"
        options:
          - "Yes"
          - "No"
        timeout: 300
    # 2. Wait for the response event
    - wait_for_trigger:
        - platform: event
          event_type: matrix_messenger_response
          event_data:
            room_id: "!abc123:matrix.org"
      timeout: "00:05:00"
      continue_on_timeout: true
    # 3. Branch
    - choose:
        - conditions:
            - condition: template
              value_template: "{{ wait.trigger.event.data.response == 'Yes' }}"
          sequence:
            - action: alarm_control_panel.alarm_disarm
              target:
                entity_id: alarm_control_panel.home
        default:
          - action: notify.matrix_wohnzimmer
            data:
              message: "Alarm not confirmed — police notified."

---

React to emoji reactions (👍 / 👎)

automation:
  alias: "Heating approval"
  trigger:
    - platform: time
      at: "17:00:00"
  action:
    - action: matrix_messenger.ask_question
      data:
        room_id: "!abc123:matrix.org"
        question: "Turn on heating now?"
        options:
          - "👍"
          - "👎"
        timeout: 900
    - wait_for_trigger:
        - platform: event
          event_type: matrix_messenger_response
          event_data:
            room_id: "!abc123:matrix.org"
      timeout: "00:15:00"
      continue_on_timeout: true
    - if:
        - condition: template
          value_template: "{{ wait.trigger.event.data.response == '👍' }}"
      then:
        - action: climate.turn_on
          target:
            entity_id: climate.living_room

---

E2EE key storage

The integration stores matrix-nio's E2EE keys (Olm/Megolm sessions) in:

<ha-config-dir>/.storage/matrix_messenger/

Back this directory up together with your HA config. If it is deleted, the integration will re-upload keys and may lose access to past encrypted messages.

---

Troubleshooting

Symptom	Cause	Fix
ImportError: libolm on startup	libolm not installed	apt install libolm-dev (HA Core only)
Rooms list is empty after login	Account not joined to any rooms	Join at least one room in your Matrix client first
Encrypted messages not decrypted	Keys missing (first sync)	Wait for the first full sync to complete after setup
ask_question never fires event	Sync not running	Enable background sync in the integration options, or check that no timeout expired

---

License

MIT