Set up Matrix (riot.im) notifications using the discourse-chat-integration plugin


(David Taylor) #1

This #howto describes how to setup the Matrix (riot.im) 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 riot.im web client. Equivalent steps should be possible using other interfaces.

  1. Open Riot 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. Under Settings (cog icon in bottom left), you can set the bot’s display name and avatar

  5. At the bottom of the settings page, under Advanced, copy the “Access Token” - you’ll need it later.

  6. 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)

  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 riot 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 riot.im 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 riot.im 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.


Chatroom Integration Plugin (discourse-chat-integration)