Bridging to Matrix

From AAGRINDER wiki
Jump to navigationJump to search

AAGRINDER in-game chat can be bridged to Matrix. There are two ways to achieve this: setting up a Matrix appservice, or setting up a Matrix bot.

Setting up AAGRINDER Matrix Appservice[edit]

AAGRINDER can be bridged to Matrix as an appservice. An appservice is a component ("plugin") of your Matrix homeserver, able to create new accounts to represent in-game users. This is the recommended way to bridge AAGRINDER to Matrix.

Prerequisites[edit]

You will need a Matrix Synapse homeserver.

In the AAGRINDER server directory, run the following command to install the optional dependencies:

npm install matrix-bot-sdk sharp uuid js-yaml

AAGRINDER server configuration[edit]

In your config.json in the AAGRINDER server directory, set the following configuration parameters:

  • set matrix_room_id to the ID of the room where you would like bridged messages to appear (begins with a "!")
  • set matrix_homeserver_url to the full URL to your Synapse instance (eg. https://matrix.myawesomedomain.net)
  • set matrix_appservice_enabled to true
  • set matrix_appservice_id to aagrinder (unless you already have an appservice with this ID)
  • set matrix_appservice_url to the URL where the AAGRINDER server will be accessible from Synapse, port included. This might be for example http://localhost:8433, or, if Synapse will be running in Docker, something like http://172.17.0.1:8433
  • set matrix_appservice_domain to the name of your Matrix homeserver name, for example myawesomedomain.net
  • set matrix_appservice_bindadress to the address where AAGRINDER will be listening for requests from Synapse. This might be localhost, or, if Synapse will be running in Docker, something like 172.17.0.1
  • set matrix_appservice_port to the port number on which AAGRINDER will be listening for requests from Synapse. The default is 8433.

Appservice registration[edit]

Generate your appservice registration file by running the following command in the AAGRINDER server direcory:

npm run registration

mx-aagrinder-registration.yaml will be created. Verify that the bind address is correct (see previous section).

Copy the AAGRINDER registration file to an accessible directory for the Matrix server (for example next to homeserver.yaml).

Edit homeserver.yaml. Add the path to the AAGRINDER registration file in the section app_service_config_files.

Restart Synapse and AAGRINDER.

Setting up AAGRINDER Matrix bot[edit]

AAGRINDER can be bridged to Matrix through a bot user. The bot is a regular Matrix account. The AAGRINDER server will have the access token of the account and will be able to control it.

Please note that this method has not been tested in a long time because the appservice way is better. You really should run your own Matrix server, even if you have it only for the AAGRINDER bridge.

Prerequisites[edit]

You will need a new Matrix account that you are not using for anything else. Join the room where you would like the bridged messages to appear.

In the AAGRINDER server directory, run the following command to install the optional dependencies:

npm install matrix-bot-sdk sharp

AAGRINDER server configuration[edit]

In your config.json in the AAGRINDER server directory, set the following configuration parameters:

  • set matrix_room_id to the ID of the room where you would like bridged messages to appear (begins with a "!")
  • set matrix_homeserver_url to the full URL to your Synapse instance (eg. https://matrix.example.com)
  • set matrix_bot_enabled to true
  • set matrix_bot_access_token to the Matrix account's access token, which you can extract from any Matrix client where the account is currently logged in.

Restart AAGRINDER for changes to take effect.