Matrix
This integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to send messages to matrix rooms, as well as to react to messages in matrix rooms. Reacting to commands is accomplished by firing an event when one of the configured commands is triggered.
There is currently support for the following device types within Home Assistant:
Configuration
To enable the Matrix integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], add it to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file.
After changing the configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file, restart Home Assistant to apply the changes. The integration is now shown on the integrations page under Settings > Devices & services. Its entities are listed on the integration card itself and on the Entities tab.
# Example configuration.yaml entry
matrix:
homeserver: https://matrix.org
username: "@my_matrix_user:matrix.org"
password: supersecurepassword
rooms:
- "#hasstest:matrix.org"
commands:
- word: my_command
name: my_command
Configuration Variables
The matrix username that Home Assistant should use to log in. Note: You must specify a full matrix ID here, including the homeserver domain, e.g., ‘@my_matrix_bot:matrix.org’. Please note also that the ‘@’ character has a special meaning in YAML, so this must always be given in quotes.
The full URL for your homeserver. If you use the default matrix.org homeserver, this is ‘https://matrix.org
The list of rooms that the bot should join and listen for commands (see below) in. While you can limit the list of rooms that a certain command applies to on a per-command basis (see below), you must still list all rooms here that commands should be received in. Rooms can be given either by their internal ID (e.g., ‘!cURbafjkfsMDVwdRDQ:matrix.org’) or any of their aliases (e.g., ‘#matrix:matrix.org’).
A list of commands that the bot should listen for. If a command is triggered (via its word or expression, see below), an event is fired that you can handle using automations. Every command consists of these possible configuration options:
Specifies a word that the bot should listen for. If you specify ‘my_command’ here, the bot will react to any message starting with ‘!my_command’.
Specifies a regular expression (in Python regexp syntax) that the bot should listen to. The bot will react to any message that matches the regular expression.
The name of the command. This will be an attribute of the event that is fired when this command triggers.
In order to prevent infinite loops when reacting to commands, you have to use a separate account for the Matrix integration.
Event data
If a command is triggered, a matrix_command
event is fired. The event contains the name of the command in the name
field.
If the command is a word command, the data
field contains a list of the command’s arguments, i.e., everything that stood behind the word, split at spaces. If the command is an expression command, the data
field contains the group dictionary
Comprehensive Configuration Example
This example also uses the matrix notify
platform.
# The Matrix integration
matrix:
homeserver: https://matrix.org
username: "@my_matrix_user:matrix.org"
password: supersecurepassword
rooms:
- "#hasstest:matrix.org"
- "#someothertest:matrix.org"
commands:
- word: testword
name: testword
rooms:
- "#someothertest:matrix.org"
- expression: "My name is (?P<name>.*)"
name: introduction
notify:
- name: matrix_notify
platform: matrix
default_room: "#hasstest:matrix.org"
automation:
- alias: "React 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"
- alias: "React to an introduction"
triggers:
- trigger: event
event_type: matrix_command
event_data:
command: introduction
actions:
- action: notify.matrix_notify
data:
message: "Hello {{trigger.event.data.args['name']}}"
This configuration will:
- Listen for “!testword” in the room “#someothertest:matrix.org” (and only) there. If such a message is encountered, it will answer with “It looks like you wrote !testword” into the “#hasstest:matrix.org” channel.
- Listen in both rooms for any message matching “My name is
” and answer with “Hello ” into “#hasstest:matrix.org”.
Notifications
The matrix
platform allows you to deliver notifications from Home Assistant to a Matrix
To enable Matrix notifications in your installation, you first need to configure the Matrix integration. Then, add the following to your configuration.yaml
The configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more] file:
# Example configuration.yaml entry
notify:
- name: NOTIFIER_NAME
platform: matrix
default_room: ROOM_ID_OR_ALIAS
The target room has to be precreated, the room id can be obtained from the rooms settings dialog. Rooms by default have a canonical id of the form "!<randomid>:homeserver.tld"
, but can also be allocated aliases like "#roomname:homeserver.tld"
. Make sure to use quotes around the room id or alias to escape special characters (!
, and #
) in YAML. The notifying account may need to be invited to the room, depending on the individual rooms policies.
To use notifications, please see the getting started with automation page.
Message formats
Matrix supports sending messages using a limited HTML subsetdata
.
Supported formats are: text
(default), and html
.
# Example of notification as HTML
actions:
- action: notify.matrix_notify
data:
message: >-
<h1>Hello, world!</h1>
data:
format: "html"
Images in notification
It is possible to send images with notifications. To do so, add a list of paths in the notification data
.
# Example of notification with images
actions:
- action: notify.matrix_notify
data:
message: "Test with images"
data:
images:
- /path/to/picture.jpg
If you need to include a file from an external folder in your notifications, you will have to list the source folder as allowed.
configuration.yaml
...
homeassistant:
allowlist_external_dirs:
- /tmp