Added D8 Rules support to Matrix API

As of today, the Drupal Matrix API module now supports sending messages to a room via Rules. Now you can automatically configure notifications to Matrix rooms without touching any code!

This is useful if you want to get notified in a Matrix room of some event on your website, such as a new comment, a user registration, updated content, etc.

Rules is still in Alpha, and has some UI quirks, but it works fine.

To set up a notification of new content in a Matrix Room:

1. Create a Matrix account

First, your site needs a Matrix account. Easiest is to set up an account using Riot.im for your site. You can also set up a site on your own homeserver using normal account creation processes.

2. Install the necessary modules

Next, install these modules on your site, using normal Drupal module installation steps:

• matrix_api
• rules
• typed_data
• token

3. Configure the Matrix API Settings

Then, go to Administration -> Configuration -> Web services -> Matrix API settings, and configure your account. Specify a custom homeserver if the account is not on matrix.org, and provide either an authentication token or a MX id and password.

If the Matrix API does not successfully authenticate, you will get an error message.

4. Configure the notification rules

1. Go to Administration -> Configuration -> Workflow -> Rules
2. Add a new "Reaction Rule"
3. Provide a label for the rule, and choose the event you want to receive a notification for -- e.g. "After saving new content"
4. Under "Actions", click "Add Action" and fill out the following:

• Room Alias: use any alias for the room you want to post this message in
• Message: Enter the message to post. Tokens will be replaced, and you can pass a single Data entity into the token system to use for replacements.
• Data: "Switch to data selection" and then you can select the entity that triggered the event (or any other entities you might add in other conditions). Whatever entity you provide here will be used for token replacement, with the first part of the token the entity type - e.g. "node", "user", "comment".

5. Save the action.
6. IMPORTANT! Save the rule. (If you don't do this, the action won't fire!)
7. Clear caches -- the rule will not fire until after a cache rebuild.

That's it! You now have a rule that sends a Matrix message to a room when content is added to the site.

Notes

The site attempts to join the room before sending a message. If the room does not exist, or the account does not have permission to enter the room, you will get an error.

You can invite the site's account to a restricted room, and it will join when it attempts to send the first message to that room.

The Drupal Matrix API module does not currently support E2E encryption.

What's next?

The Rules UI still seems bare-bones -- I did not find a way to create a long-text field, or display the Token browser. You can go to the Token module help page to pull up a token browser for all entities on the site, and find the right tokens to use. As Rules develops, we will plan to provide better support for this.

We also plan to provide a message_notify plugin, so that users of the Message family of modules can easily send Matrix messages.

Can we help with your Matrix or Drupal integration? Contact us, or leave a comment below!