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.
$ git clone ... $ cd matrix-appservice-slack $ npm install
Create a new Matrix room to act as the administration control room. Note its internal room ID.
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
$SLACK_PORTin the remaining instructions.
config.yamlfile for global configuration. There is a sample one to begin with in
config/config.sample.yamlyou 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."
Generate the appservice registration file (if the application service runs on the same server you can use
$ node app.js -r -c config.yaml -u "http://$HOST:$MATRIX_PORT"
Start the actual application service. You can use forever
$ forever start app.js -c config.yaml -p $MATRIX_PORT
$ node app.js -c config.yaml -p $MATRIX_PORT
Copy the newly-generated
slack-registration.yamlfile to the homeserver. Add the registration file to your homeserver config (default
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.
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_usernamefield of the config file, and the homeserver's domain name. For example:
The bridge itself should now be running.
To actually use it, you will need to configure some linked channels.
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.
Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like
Create a Slack channel in the usual manner.
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
Add an "Outgoing WebHooks" integration to the Slack channel and take a note of its
tokenfield. 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
linkcommand 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 :)
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.