vps/docs/home-assistant-matrix.md

# Home Assistant × Matrix integration

Reference for wiring the Home Assistant [Matrix integration](https://www.home-assistant.io/integrations/matrix)
to the self-hosted Matrix homeserver at [`synapse.chans.xyz`](../hosts/synapse.chans.xyz.md).
Deliberately contains no Matrix passwords, access tokens, or room encryption material.

## Purpose

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`:

```yaml
action: notify.matrix_notify
data:
  message: "Reply message goes here"
  data:
    thread_id: "{{ trigger.event.data.thread_parent }}"
```

## Actions

- `matrix.react` — send a reaction to a message in a Matrix room
  (`reaction`, `room`, `message_id`).
- `matrix.send_message` — send a message to one or more Matrix rooms.

## Comprehensive example (adapted)

```yaml
matrix:
  homeserver: https://synapse.chans.xyz
  username: "@ha_bot:chans.xyz"
  password: supersecurepassword
  rooms:
    - "#hasstest:chans.xyz"
    - "#someothertest:chans.xyz"
  commands:
    - word: testword
      name: testword
      rooms:
        - "#someothertest:chans.xyz"
    - expression: "My name is (?P<name>.*)"
      name: introduction
    - reaction: 👍
      name: thumbsup

notify:
  - name: matrix_notify
    platform: matrix
    default_room: "#hasstest:chans.xyz"

automation:
  - alias: "Respond to !testword"
    triggers:
      - trigger: event
        event_type: matrix_command
        event_data:
          command: testword
    actions:
      - action: notify.matrix_notify
        data:
          message: "It looks like you wrote !testword"
```

## References

- Home Assistant Matrix integration: <https://www.home-assistant.io/integrations/matrix>
- Matrix host facts: [`hosts/synapse.chans.xyz.md`](../hosts/synapse.chans.xyz.md)
- Matrix deployment and upstream index: [`matrix-upstream.md`](matrix-upstream.md)
- Hermes Agent Matrix channel (MAS local-password + access-token pattern): [`hermes-matrix.md`](hermes-matrix.md)
- HA host facts: [`hosts/hass.windy.lan.md`](../hosts/hass.windy.lan.md)
- HA maintenance runbook: [`runbooks/home-assistant-maintenance.md`](../runbooks/home-assistant-maintenance.md)