A Matrix <--> Slack bridge
JavaScript
Clone or download
Half-Shot Merge pull request #79 from matrix-org/hs/unpin-mab
Don't pin on matrix-appservice-bridge anymore
Latest commit 72693a2 Jul 10, 2018

README.md

matrix-appservice-slack

A Matrix <--> Slack bridge

This is currently a very barebones bridge, it just does basic text in pre-enumerated channels. It will become more exciting.

Installation

$ git clone ...
$ cd matrix-appservice-slack
$ npm install

Setup

  1. Create a new Matrix room to act as the administration control room. Note its internal room ID.

  2. Pick/decide on two spare local TCP port numbers to use. One will listen for messages from Matrix and needs to be visible to the homeserver. The other will listen for messages from Slack and needs to be visible to the internet. Take care to configure firewalls appropriately. These ports will be notated as $MATRIX_PORT and $SLACK_PORT in the remaining instructions.

  3. Create a config.yaml file for global configuration. There is a sample one to begin with in config/config.sample.yaml you may wish to copy and edit as appropriate.

    At minimum this needs to contain:

    slack_hook_port: $SLACK_PORT
    bot_username: "localpart for the bot's own user account"
    username_prefix: "localpart prefix for generated ghost users"
    
    homeserver:
      url: "http URL pointing at the homeserver"
      server_name: "domain part of the homeserver's name. Used for
                    ghost username generation"
    
    matrix_admin_room: "the ID of the room created in step 1."
  4. Generate the appservice registration file (if the application service runs on the same server you can use localhost as the $HOST name):

    $ node app.js -r -c config.yaml -u "http://$HOST:$MATRIX_PORT"
  5. Start the actual application service. You can use forever

    $ forever start app.js -c config.yaml -p $MATRIX_PORT

    or node

    $ node app.js -c config.yaml -p $MATRIX_PORT
  6. Copy the newly-generated slack-registration.yaml file to the homeserver. Add the registration file to your homeserver config (default homeserver.yaml):

    app_service_config_files:
       - ...
       - "/path/to/slack-registration.yaml"

    Don't forget - it has to be a YAML list of strings, not just a single string.

    Restart your homeserver to have it reread the config file an establish a connection to the bridge.

  7. Invite the bridge bot user into the admin room, so it can actually see and respond to commands. The bot's user ID is formed from the bot_username field of the config file, and the homeserver's domain name. For example:

    /invite @slackbot:my.server.here
    

The bridge itself should now be running.

To actually use it, you will need to configure some linked channels.

Provisioning

This bridge allows linking together pairs of Matrix rooms and Slack channels, relaying messages said by people in one side into the other. To create a link first the individual Matrix room and Slack channel need to be created, and then a command needs to be issued in the administration console room to add the link to the bridge's database.

  1. Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !aBcDeF:example.com.

  2. Create a Slack channel in the usual manner.

  3. Add an "Incoming WebHooks" integration to the Slack channel and take a note of its "Webhook URL" from the integration settings in Slack - it will look something like https://hooks.slack.com/services/ABC/DEF/123.

  4. Add an "Outgoing WebHooks" integration to the Slack channel and take a note of its token field. Add a URL to this web hook pointing back at the application service port you configured during setup.

    You will also need to determine the "channel ID" that Slack uses to identify the channel. Unfortunately, it is not easily obtained from the Slack UI. The easiest way to do this is to send a message from Slack to the bridge; the bridge will log the channel ID as part of the unrecognised message output. You can then take note of the channel_id field.

  5. Issue a link command in the administration control room with these collected values as arguments:

    link --channel CHANNELID --room !the-matrix:room.id --token THETOKEN --webhook_uri http://the.webhook/uri
    

    These arguments can be shortened to single-letter forms:

    link -c CHANNELID -r !the-matrix:room.id -t THETOKEN -u http://the.webhook/uri
    

See also https://github.com/matrix-org/matrix-appservice-bridge/blob/master/HOWTO.md for the general theory of all this :)

Mattermost

Because Mattermost's webhook APIs are Slack-compatible, the Matrix <--> Slack bridge also works with it. The webhook configuration is very similar to Slack's and is documented on Mattermost's website.