v1.1.0: per-room services, send_to_user, mautrix bridge support, searchable room picker
- Add per-room convenience actions (matrix_messenger.send_to_<roomname>) - Add send_to_user action: finds existing portal/DM room or creates one; supports mautrix-whatsapp, -signal, -telegram puppet IDs - Inject service descriptions dynamically so room dropdowns show friendly names instead of room IDs (full-state sync + direct state API fallback) - Switch all room selectors to searchable dropdown mode - Fix _find_or_create_dm to match bridge portal rooms (3+ members) - Fix async_get_joined_rooms to use full_state sync - Bump version to 1.1.0 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Marc
@@ -1,17 +1,20 @@
|
||||
# Matrix Messenger for Home Assistant
|
||||
|
||||
Send messages from Home Assistant to [Matrix](https://matrix.org) rooms — including encrypted rooms (E2EE). Ask questions and react to text replies or emoji reactions in automations.
|
||||
Send messages from Home Assistant to [Matrix](https://matrix.org) rooms — including encrypted rooms (E2EE). Ask questions and react to text replies or emoji reactions in automations. Supports mautrix bridges (WhatsApp, Signal, Telegram) out of the box.
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
- **Send messages** to configured rooms via service call or `notify.*` entity
|
||||
- **Per-room services** — one dedicated action per room, selectable by friendly name
|
||||
- **Direct messages** — send to any Matrix user or mautrix bridge contact without pre-configuring a room
|
||||
- **Ask questions** — send a question and wait for a text reply or emoji reaction
|
||||
- **mautrix bridge support** — WhatsApp, Signal, Telegram via `send_to_user`
|
||||
- **E2EE support** — end-to-end encrypted rooms via [matrix-nio](https://github.com/poljar/matrix-nio)
|
||||
- **Searchable room picker** — filterable dropdown in all actions and config dialogs
|
||||
- **Two auth methods** — username + password, or access token
|
||||
- **Fully GUI-configurable** — no YAML required, all settings via the HA config flow
|
||||
- **HACS-installable**
|
||||
- **Fully GUI-configurable** — no YAML required
|
||||
|
||||
---
|
||||
|
||||
@@ -73,7 +76,7 @@ Retrieve your token in your Matrix client: **Settings → Security → Sessions
|
||||
|
||||
### Step 3 — Room Selection
|
||||
|
||||
All rooms the account has joined are listed. Select one or more rooms.
|
||||
All rooms the account has joined are listed with their display names. Select one or more rooms using the searchable dropdown.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -81,19 +84,32 @@ All rooms the account has joined are listed. Select one or more rooms.
|
||||
|
||||
## Reconfiguring rooms
|
||||
|
||||
Go to **Settings → Devices & Services → Matrix Messenger → Configure** to change the selected rooms or toggle background sync at any time.
|
||||
Go to **Settings → Devices & Services → Matrix Messenger → Configure** to change the selected rooms or toggle background sync at any time. Rooms you have since left will no longer appear in the list and are removed from the configuration when you save.
|
||||
|
||||
---
|
||||
|
||||
## Services / Actions
|
||||
|
||||
### `matrix_messenger.send_to_<roomname>`
|
||||
|
||||
One dedicated action is created for each configured room. No `room_id` parameter needed — just type the message.
|
||||
|
||||
**Example** (room named "Wohnzimmer"):
|
||||
```yaml
|
||||
action: matrix_messenger.send_to_wohnzimmer
|
||||
data:
|
||||
message: "Waschmaschine fertig."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### `matrix_messenger.send_message`
|
||||
|
||||
Sends a plain-text message to a room.
|
||||
Sends a plain-text message to a room selected from a searchable dropdown.
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `room_id` | string | ✓ | Matrix room ID, e.g. `!abc123:matrix.org` |
|
||||
| `room_id` | string | ✓ | Selected from configured rooms |
|
||||
| `message` | string | ✓ | Message text |
|
||||
|
||||
**Example:**
|
||||
@@ -106,13 +122,54 @@ data:
|
||||
|
||||
---
|
||||
|
||||
### `matrix_messenger.send_to_user`
|
||||
|
||||
Sends a direct message to a Matrix user. Searches all joined rooms for one that contains the target user; if none is found, a new DM room is created.
|
||||
|
||||
Works with **mautrix bridge puppets** (WhatsApp, Signal, Telegram) as long as a portal room for that contact already exists (i.e. you have chatted with the contact before via the bridge).
|
||||
|
||||
| Parameter | Type | Required | Description |
|
||||
|---|---|---|---|
|
||||
| `user_id` | string | ✓ | Matrix user ID, e.g. `@user:matrix.org` |
|
||||
| `message` | string | ✓ | Message text |
|
||||
|
||||
**Example — native Matrix user:**
|
||||
```yaml
|
||||
action: matrix_messenger.send_to_user
|
||||
data:
|
||||
user_id: "@marc:matrix.org"
|
||||
message: "Alarm triggered!"
|
||||
```
|
||||
|
||||
**Example — WhatsApp contact via mautrix-whatsapp:**
|
||||
```yaml
|
||||
action: matrix_messenger.send_to_user
|
||||
data:
|
||||
user_id: "@whatsapp_4917612345678:your.server"
|
||||
message: "Doorbell rang."
|
||||
```
|
||||
|
||||
#### Bridge puppet ID format
|
||||
|
||||
| Bridge | User ID format |
|
||||
|---|---|
|
||||
| WhatsApp | `@whatsapp_<number without +>:<server>` |
|
||||
| Signal | `@signal_<number without +>:<server>` |
|
||||
| Telegram | `@telegram_<user id>:<server>` |
|
||||
|
||||
Find the exact puppet ID in your Matrix client (e.g. Element) under the contact's profile → Matrix ID.
|
||||
|
||||
> **Note:** Messages sent via bridge puppets appear to the recipient as coming from your Matrix account — this is how mautrix bridges work by design.
|
||||
|
||||
---
|
||||
|
||||
### `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 |
|
||||
| `room_id` | string | ✓ | — | Selected from configured rooms |
|
||||
| `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 |
|
||||
@@ -137,11 +194,6 @@ data:
|
||||
timeout: 300
|
||||
```
|
||||
|
||||
The integration appends the options to the message:
|
||||
> Alarm triggered — is this a false alarm?
|
||||
>
|
||||
> Mögliche Antworten: Yes / No
|
||||
|
||||
---
|
||||
|
||||
## Notify entities
|
||||
@@ -174,7 +226,7 @@ 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) |
|
||||
| `question_id` | string (UUID) | Unique ID of the question |
|
||||
| `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 |
|
||||
@@ -193,9 +245,8 @@ automation:
|
||||
entity_id: binary_sensor.front_door_motion
|
||||
to: "on"
|
||||
action:
|
||||
- action: matrix_messenger.send_message
|
||||
- action: matrix_messenger.send_to_wohnzimmer
|
||||
data:
|
||||
room_id: "!abc123:matrix.org"
|
||||
message: "Motion detected at the front door."
|
||||
```
|
||||
|
||||
@@ -211,7 +262,6 @@ automation:
|
||||
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"
|
||||
@@ -220,7 +270,6 @@ automation:
|
||||
- "Yes"
|
||||
- "No"
|
||||
timeout: 300
|
||||
# 2. Wait for the response event
|
||||
- wait_for_trigger:
|
||||
- platform: event
|
||||
event_type: matrix_messenger_response
|
||||
@@ -228,7 +277,6 @@ automation:
|
||||
room_id: "!abc123:matrix.org"
|
||||
timeout: "00:05:00"
|
||||
continue_on_timeout: true
|
||||
# 3. Branch
|
||||
- choose:
|
||||
- conditions:
|
||||
- condition: template
|
||||
@@ -298,8 +346,10 @@ The integration stores matrix-nio's E2EE keys (Olm/Megolm sessions) in:
|
||||
|---|---|---|
|
||||
| `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 |
|
||||
| Room names show as IDs | Stale `.pyc` cache on network share | Delete `__pycache__/` in the component folder and restart HA |
|
||||
| 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 |
|
||||
| `ask_question` never fires event | Sync not running | Enable *background sync* in options, or check that no timeout expired |
|
||||
| `send_to_user` fails for bridge contact | No portal room exists yet | Start one conversation with the contact in Element first |
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user