The integration lets Home Assistant send messages to Matrix rooms and react to
messages/reactions in Matrix rooms. "Reacting" is done by firing a
`matrix_command` event when one of the configured commands matches; automations
then trigger on that event. Sending is done through the `notify.matrix` platform
and the `matrix.send_message` / `matrix.react` actions.
## Environment mapping
| Integration setting | This deployment |
|---|---|
| `homeserver` | `https://synapse.chans.xyz` (client-server base URL) |
| `username` | full Matrix ID, e.g. `@ha_bot:chans.xyz` |
| `password` | MAS local-password account password (see below) |
| Room IDs / aliases | full forms with the identity domain, e.g. `!cUrbafjkfsMDVwdRDQ:chans.xyz` or `#room:chans.xyz` |
- Identity domain is `chans.xyz` (not `synapse.chans.xyz`); user IDs and room
aliases carry the `:chans.xyz` suffix.
- Authentication on this homeserver is MAS (Matrix Authentication Service) with
local-password accounts. The integration logs in with `m.login.password`
(username + password), so the bot account must be a local-password account —
same as the Hermes account documented in [`hermes-matrix.md`](hermes-matrix.md).
If MAS is later switched to OAuth2/OIDC-only (no legacy password login), the
integration's password login will stop working; keep that in mind before such
a change.
- Public registration is disabled. Create/reset the dedicated bot account via
MAS / Element Admin.
## Use a separate bot account (mandatory)
The docs are explicit: to prevent infinite loops when reacting to commands,
the integration **must** use a separate account from any account whose messages
it reacts to. Use a dedicated account such as `@ha_bot:chans.xyz`, not a human
account.
## configuration.yaml (example)
```yaml
# The Matrix integration
matrix:
homeserver:https://synapse.chans.xyz
username:"@ha_bot:chans.xyz"
password:supersecurepassword
rooms:
- "#hasstest:chans.xyz"
commands:
- word:my_command
name:my_command
```
After changing `configuration.yaml`, restart Home Assistant to apply the
changes. The integration then shows under **Settings → Devices & services**;
its entities are on the integration card and the Entities tab.
### Configuration variables
| Variable | Meaning |
|---|---|
| `username` | Full Matrix ID the bot logs in as, e.g. `@ha_bot:chans.xyz`. The `@` has a special YAML meaning, so always quote it. |
| `password` | The bot account's password (MAS local password). |
| `homeserver` | Full client-server URL of the homeserver. |
| `rooms` | Rooms the bot should join and listen in. List **all** rooms commands are to be received in, even if a command scopes itself to fewer rooms. Accepts internal room ID (`!…:chans.xyz`) or alias (`#room:chans.xyz`). |
| `commands` | Commands to listen for. Each fires a `matrix_command` event when triggered. |
### Command types
| Key | Triggers when |
|---|---|
| `word` | A message starts with `!<word>`. Arguments after the word are captured as a list in the event's `data`. |
| `expression` | A message matches the Python regexp. The regexp group dictionary is captured in the event's `data`. |
| `reaction` | A message is reacted to with the given emoji. |
| `name` | The command name, exposed as an attribute of the fired event. |
A command can be scoped to specific rooms with a per-command `rooms` list (the
room must still be listed under the top-level `rooms`).
## Event data
When a command triggers, a `matrix_command` event fires with:
-`name` — the command name.
-`data` — for `word` commands, a list of arguments (everything after the word,
split on spaces); for `expression` commands, the group dictionary of the
matching regexp.
-`event_id` — the received message's identifier.
-`thread_parent` — the root message ID of the thread; equals `event_id` when
the message is not inside a thread.
## Notifications (notify.matrix)
Deliver notifications from Home Assistant to a Matrix room (direct or group):
```yaml
notify:
- name:matrix_notify
platform:matrix
default_room:"#hasstest:chans.xyz"
```
- The target room must already exist; get its canonical ID from the room
settings dialog (`!<randomid>:chans.xyz`) or an alias (`#roomname:chans.xyz`).
Quote the room ID/alias in YAML to escape the `!` / `#` characters.
- The notifying account may need to be invited to the room, depending on room
policy.
Message formats (`data.format`): `text` (default) and `html`. Images can be
attached via `data.images` (list of file paths); files from outside allowed
folders require `homeassistant.allowlist_external_dirs` to list the source
folder.
Reply inside a thread by passing the root message ID into `data.thread_id`:
