Set up Matrix (element.io) notifications using the discourse-chat-integration plugin

This #howto describes how to setup the Matrix (element.io) provider included in discourse-chat-integration.

Thanks to @ara4n and members of the #matrix-dev:matrix.org room for their help with this integration :slight_smile:

Install

If you haven’t already, install the discourse-chat-integration plugin

Set up Matrix

These instructions assume you are using the element.io web client. Equivalent steps should be possible using other interfaces.

  1. Open https://app.element.io/ in a new incognito window (you’ll see why later)

  2. Create a user account for your bot. You’ll probably want to write down the password somewhere in case you want to log back in later. Discourse does not need it.

  3. Use the interface to join any rooms that you want to be able to send notifications to

  4. Open the user settings by clicking your avatar in the top left, then All Settings

  5. Configure the bot’s display name and avatar

  6. Switch to the “Help and About” tab, scroll down to “Advanced”, and copy the Homeserver address and your “Access Token” - you’ll need them later.

  7. DO NOT CLICK LOG OUT. If you do, the Access Token will be invalidated, and it won’t work. Instead, just close the incognito window. If you forgot to open an incognito window, go back to step 1 :wink:

Set up Discourse

  1. In your Discourse site settings, enter your home server address in the chat_integration_matrix_homeserver setting. Make sure to include the protocol. (e.g. https://matrix.org). Do not include a trailing slash.

  2. Paste the access token you copied earlier into the chat_integration_matrix_access_token site setting

  3. Enable chat_integration_matrix_enabled

  4. Go to the Plugins tab, then Chat Integration

  5. Go to the Matrix tab, then Add Channel

  6. Enter a name for the channel (this is only displayed in the admin interface, it can be anything)

  7. Enter the “Room ID” for a room that you want to send notifications to. In the Element web client, you can find it by opening your room, clicking the name at the top, then scroll to the bottom. It will look something like

    !cdGUowUAqlgLHVerqE:matrix.org
    
  8. Save Channel

  9. Use the Test button on the channel you just created to check that everything’s working. You should see something like this:
    17

  10. Set up some “Rules” for your channel, according to the discourse-chat-integration instructions.

  11. giphy-downsized (1)

Technical Notes
  • At the time of writing, there does not seem to be a way of obtaining an “access token” for a “bot” in a user-friendly way. The incognito window solution is the most user-friendly way I could find

  • The matrix spec does not currently define a way of providing “rich text” messages. There is a spec under development, but for now this plugin uses the “unofficial” method which has been adopted in the element.io client. Clients that do not support this will simply fall back to a plain text message

  • There is no provision in this implementation for ‘refreshing’ access tokens. This is based on the understanding that the majority of homeservers currently in use do not expire tokens. If this changes in the future, this will need to be revisited.

16 Likes

The test is not working for us:

422 No Reason Phrase

and the spinner will keep on turning indefinitely until full page reload. How can we triage the error?

3 Likes

I just tried setting up a matrix integration using the instructions above, and it all worked ok. Can you confirm that you’re running the latest version of Discourse and this plugin?

Are you using the matrix.org homeserver, or your own homeserver? The 422 error is coming from that server.

I would suggest double checking your channel identifier, and also your matrix access token in your Discourse site settings.

4 Likes

Thanks for the hints. I’ll try that out, before reporting back here.

3 Likes

I have absolutely the same issue as @almereyda has.
@david, can you update obtaing “Access Token”, please? (Riot seems to be intensively developed :+1:)
+“Doctor log

2 Likes

I’m also interested in updated instructions about getting an access token…

1 Like

Currently called Room settings in Element (rebranding of Riot).

Works perfectly.

2 Likes

I’ve updated this page to reflect that change.

The access token is, apparently, now under “Help and About” at the bottom of Settings.

I have the same infinite-spinner problem. :frowning:

I tried with rooms on both matrix.org and fedora.im.

1 Like

I just ran through the setup myself and it seemed to work ok. A couple of theories:

  • Are your rooms encrypted? I’m not sure if we need to do extra work to support encrypted rooms

  • Maybe the access tokens expire after some time. This didn’t used to happen when I build the integration in 2017, but that was a long time ago :older_man:. I’ll try my local config again later this week and see if it still works.

1 Like

They are not.

Maybe, but I was copying the access token and then using it basically immediately and that didn’t help.

3 Likes

For the record, @mattdm and I were able to track this down to a trailing slash on the Homeserver URL in the Discourse settings.

I’ve added a note about this to the instructions in the OP, and also updated the access token instructions to work with the latest element.io UI.

3 Likes