|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: "Matrix" |
| 4 | +description: "Matrix chatbot support" |
| 5 | +date: 2018-03-25 18:50 |
| 6 | +sidebar: true |
| 7 | +comments: false |
| 8 | +sharing: true |
| 9 | +footer: true |
| 10 | +logo: matrix.png |
| 11 | +ha_category: Hub |
| 12 | +--- |
| 13 | + |
| 14 | +This component 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. |
| 15 | + |
| 16 | +```yaml |
| 17 | +# Example configuration.yaml entry |
| 18 | +matrix: |
| 19 | + homeserver: https://matrix.org |
| 20 | + username: "@my_matrix_user:matrix.org" |
| 21 | + password: supersecurepassword |
| 22 | + rooms: |
| 23 | + - "#hasstest:matrix.org" |
| 24 | + commands: |
| 25 | + - word: my_command |
| 26 | +``` |
| 27 | +
|
| 28 | +Configuration variables: |
| 29 | +
|
| 30 | +- **username** (*Required*): 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. |
| 31 | +- **homeserver** (*Required*): The full URL for your homeserver. If you use the defauls matrix.org homeserver, this is "https://matrix.org". |
| 32 | +- **password** (*Required*): The password for your Matrix account. |
| 33 | +- **verify_ssl** (*Optional*): Verify the homeservers certificate. Defaults to `true`. |
| 34 | +- **rooms** (*Optional*): 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"). |
| 35 | +- **commands** (*Optional*): 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: |
| 36 | + - **word** (*Required* if **expression** is not given, *Forbidden* otherwise): 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". |
| 37 | + - **expression** (*Required* if **word** is not given, *Forbidden* otherwise): 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. |
| 38 | + - **name** (*Required* if **expression** is given, *Optional* otherwise): The name of the command. This will be an attribute of the event that is fired when this command triggers. |
| 39 | + - **rooms** (*Optional*): A list of rooms that the bot should listen for this command in. If this is not given, the *rooms* list from the main config is used. Please note that every room in this list must also be in the main *room* config. |
| 40 | + |
| 41 | +### {% linkable_title Event Data %} |
| 42 | + |
| 43 | +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 that has no name set, the `name` field contains the word instead. |
| 44 | + |
| 45 | +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](https://docs.python.org/3.6/library/re.html?highlight=re#re.match.groupdict) of the regular expression that matched the message. |
| 46 | + |
| 47 | +### {% linkable_title Comprehensive Configuration Example %} |
| 48 | + |
| 49 | +This example also uses the [matrix `notify` platform](/components/notify.matrix/). |
| 50 | + |
| 51 | +```yaml |
| 52 | +# The Matrix component |
| 53 | +matrix: |
| 54 | + homeserver: https://matrix.org |
| 55 | + username: "@my_matrix_user:matrix.org" |
| 56 | + password: supersecurepassword |
| 57 | + rooms: |
| 58 | + - "#hasstest:matrix.org" |
| 59 | + - "#someothertest:matrix.org" |
| 60 | + commands: |
| 61 | + - word: testword |
| 62 | + rooms: |
| 63 | + - "#someothertest:matrix.org" |
| 64 | + - expression: "My name is (?P<name>.*)" |
| 65 | + name: introduction |
| 66 | +
|
| 67 | +notify: |
| 68 | + - name: matrix_notify |
| 69 | + platform: matrix |
| 70 | + default_room: "#hasstest:matrix.org" |
| 71 | +
|
| 72 | +automation: |
| 73 | + - alias: 'React to !testword' |
| 74 | + trigger: |
| 75 | + platform: event |
| 76 | + event_type: matrix_command |
| 77 | + event_data: |
| 78 | + command: testword |
| 79 | + action: |
| 80 | + service: notify.matrix_notify |
| 81 | + data: |
| 82 | + message: 'It looks like you wrote !testword' |
| 83 | + - alias: 'React to an introduction' |
| 84 | + trigger: |
| 85 | + platform: event |
| 86 | + event_type: matrix_command |
| 87 | + event_data: |
| 88 | + command: introduction |
| 89 | + action: |
| 90 | + service: notify.matrix_notify |
| 91 | + data_template: |
| 92 | + message: "Hello {{trigger.event.data.name}}" |
| 93 | +``` |
| 94 | + |
| 95 | +This configuration will: |
| 96 | +- 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. |
| 97 | +- Listen in both rooms for any message matching "My name is <any string>" and answer with "Hello <the string>" into "#hasstest:matrix.org". |
0 commit comments