Skip to content

Commit

Permalink
Merge pull request #89 from matrix-org/hs/perissology/slack-events
Browse files Browse the repository at this point in the history
Slack Event API Support v2
  • Loading branch information
Half-Shot authored Oct 5, 2018
2 parents 5c801bd + 87c6dad commit 0a28929
Show file tree
Hide file tree
Showing 9 changed files with 1,060 additions and 293 deletions.
86 changes: 83 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,6 @@ The bridge itself should now be running.
To actually use it, you will need to configure some linked channels.
Provisioning
------------
Expand All @@ -100,6 +99,87 @@ 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.
There are 2 ways to bridge a room. The recommended way uses the newer Slack events api
and bot users. This allows you to link as many channels as you would like with only
1 Slack integration. The legacy way uses incoming/outgoing webhooks, and requires
2 Slack integrations per channel to be bridged.
### Recommended - Events API
1. Add a custom app to your Slack team/workspace by visiting https://api.slack.com/apps
and clicking on `Create New App`.
2. Name the app & select the team/workspace this app will belong to.
3. Click on `bot users` and add a new bot user. We will use this account to bridge the
the rooms.
4. Click on `Event Subscriptions` and enable them. At this point, the bridge needs to be
started as Slack will do some verification of the request rul. The request url should be
`https://$HOST:$SLACK_PORT"`. Then add the following events and save:
Bot User Events:
- team_domain_change
- message.channels
- chat:write:bot
- message.groups (if you want to bridge private channels)
- users:read
- team.info
5. Skip this step if you do not want to bridge files.
Click on `OAuth & Permissions` and add the following scopes:
- files:write:user
Note: any media uploaded to matrix is currently accessible by anyone who knows the url.
In order to make Slack files visible to matrix users, this bridge will make Slack files
visible to anyone with the url (including files in private channels). This is different
then the current behavior in Slack, which only allows authenticated access to media
posted in private channels. See [MSC701](https://github.com/matrix-org/matrix-doc/issues/701)
for details.
6. Click on `Install App` and `Install App to Workspace`. Note the access tokens show.
You will need the `Bot User OAuth Access Token` and if you want to bridge files, the
`OAuth Access Token` whenever you link a room.
7. For each channel you would like to bridge, perform the following steps:
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. Invite the bot user to the Slack channel you would like to bridge.
```
/invite @bot-user-name
```
You will also need to determine the "channel ID" that Slack uses to identify
the channel, which can be found in the url `https://XXX.slack.com/messages/<channel id>/`.
3. Issue a ``link`` command in the administration control room with these
collected values as arguments:
with file bridging:
```
link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
```
without file bridging:
```
link --channel_id CHANNELID --room !the-matrix:room.id --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
These arguments can be shortened to single-letter forms:
```
link -I CHANNELID -R !the-matrix:room.id -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
### Legacy - Webhooks
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`.
Expand All @@ -123,13 +203,13 @@ to the bridge's database.
collected values as arguments:
```
link --channel CHANNELID --room !the-matrix:room.id --token THETOKEN --webhook_uri http://the.webhook/uri
link --channel_id CHANNELID --room !the-matrix:room.id --webhook_url https://hooks.slack.com/services/ABC/DEF/123
```
These arguments can be shortened to single-letter forms:
```
link -c CHANNELID -r !the-matrix:room.id -t THETOKEN -u http://the.webhook/uri
link -I CHANNELID -R !the-matrix:room.id -u https://hooks.slack.com/services/ABC/DEF/123
```
See also https://github.com/matrix-org/matrix-appservice-bridge/blob/master/HOWTO.md for the general theory of all this :)
Expand Down
15 changes: 13 additions & 2 deletions lib/AdminCommands.js
Original file line number Diff line number Diff line change
Expand Up @@ -131,20 +131,31 @@ adminCommands.link = new AdminCommand({
required: true,
},
webhook_url: {
description: "Slack webhook URL",
description: "Slack webhook URL. Used with Slack outgoing hooks integration",
aliases: ['u'],
},
slack_bot_token: {
description: "Slack bot user token. Used with Slack bot user & Events api",
aliases: ['t'],
},
slack_user_token: {
description: "Slack user token. Used to bridge files",
}
},
func: function(main, opts, args, respond) {
return main.actionLink({
matrix_room_id: opts.room,
slack_channel_name: opts.channel,
slack_channel_id: opts.channel_id,
slack_webhook_uri: opts.webhook_url,
slack_bot_token: opts.slack_bot_token,
slack_user_token: opts.slack_user_token,
}).then(
(room) => {
respond("Room is now " + room.getStatus());
respond("Inbound URL is " + main.getInboundUrlForRoom(room));
if (room.getSlackWebhookUri()) {
respond("Inbound URL is " + main.getInboundUrlForRoom(room));
}
},
(e) => { respond("Cannot link - " + e ) }
);
Expand Down
208 changes: 208 additions & 0 deletions lib/BaseSlackHandler.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,208 @@
"use strict";

const rp = require('request-promise');
const Promise = require('bluebird');
const promiseWhile = require("./promiseWhile");
const getSlackFileUrl = require("./substitutions").getSlackFileUrl;
const log = require("matrix-appservice-bridge").Logging.get("BaseSlackHandler");

const CHANNEL_ID_REGEX = /<#(\w+)\|?\w*?>/g;
const CHANNEL_ID_REGEX_FIRST = /<#(\w+)\|?\w*?>/;

// (if the message is an emote, the format is <@ID|nick>, but in normal msgs it's just <@ID>
const USER_ID_REGEX = /<@(\w+)\|?\w*?>/g;
const USER_ID_REGEX_FIRST = /<@(\w+)\|?\w*?>/;

/**
* @constructor
* @param {Main} main the toplevel bridge instance through which to
* communicate with matrix.
*/
function BaseSlackHandler(main) {
this._main = main;
}

BaseSlackHandler.prototype.replaceChannelIdsWithNames = function(message, token) {
var main = this._main;

// match all channelIds
var testForName = message.text.match(CHANNEL_ID_REGEX);
var iteration = 0;
var matches = 0;
if (testForName && testForName.length) {
matches = testForName.length;
}
return promiseWhile(function () {
// Do this until there are no more channel ID matches
return iteration < matches;
}, function () {
// foreach channelId, pull out the ID
// (if this is an emote msg, the format is <#ID|name>, but in normal msgs it's just <#ID>
var id = testForName[iteration].match(CHANNEL_ID_REGEX_FIRST)[1];
var channelsInfoApiParams = {
uri: 'https://slack.com/api/channels.info',
qs: {
token: token,
channel: id
},
json: true
};
main.incRemoteCallCounter("channels.info");
return rp(channelsInfoApiParams).then((response) => {
let name = id;
if (response && response.channel && response.channel.name) {
log.info("channels.info: " + id + " mapped to " + response.channel.name);
name = response.channel.name;
}
else {
log.info("channels.info returned no result for " + id);
}
message.text = message.text.replace(CHANNEL_ID_REGEX_FIRST, "#" + name);
iteration++;
}).catch((err) => {
log.error("Caught error handling channels.info:" + err);
});
}).then(() => {
// Notice we can chain it because it's a Promise,
// this will run after completion of the promiseWhile Promise!
return message;
});
};

BaseSlackHandler.prototype.replaceUserIdsWithNames = function(message, token) {
var main = this._main;

// match all userIds
var testForName = message.text.match(USER_ID_REGEX);
var iteration = 0;
var matches = 0;
if (testForName && testForName.length) {
matches = testForName.length;
}
return promiseWhile(() => {
// Condition for stopping
return iteration < matches;
}, function () {
// foreach userId, pull out the ID
// (if this is an emote msg, the format is <@ID|nick>, but in normal msgs it's just <@ID>
var id = testForName[iteration].match(USER_ID_REGEX_FIRST)[1];
var usersInfoApiParams = {
uri: 'https://slack.com/api/users.info',
qs: {
token: token,
user: id
},
json: true
};
main.incRemoteCallCounter("users.info");
let response;
iteration++;
return rp(usersInfoApiParams).then((res) => {
// Technically the function only requires the team_id, so
// pass in the response to get user instead.
// Though obviously don't if the response was wrong.
response = res;
return main.getTeamDomainForMessage(
{
team_id: (res && res.user ? res.user : message).team_id,
channel: message.channel,
}
);
}).then((team_domain) => {
const user_id = main.getUserId(id, team_domain);
if (response && response.user && response.user.name) {
log.info("users.info: " + id + " mapped to " + response.user.name);
const pill = `<https://matrix.to/#/${user_id}|${response.user.name}>`;
message.text = message.text.replace(USER_ID_REGEX_FIRST, response.user.name);
message.markdownText = message.markdownText.replace(
USER_ID_REGEX_FIRST,
pill
);
return;
}
log.warn(`users.info returned no result for ${id} Response:`, response);
// Fallback to checking the user store.
var store = this.getUserStore();
return store.select({id: user_id});
}).then((result) => {
if (result === undefined) {
return;
}
let name = user_id;
log.info(`${user_id} did ${result.length > 0 ? "not" : ""} an entry`);
if (result.length) {
// It's possible not to have a displayname set.
name = result[0].display_name || result[0].id;
}
message.text = message.text.replace(USER_ID_REGEX_FIRST, name);
message.markdownText = message.markdownText.replace(
USER_ID_REGEX_FIRST,
`<https://matrix.to/#/${user_id}|${name}>`
);
}).catch((err) => {
log.error("Caught error handing users.info: " + err);
});
}).then(() => {
// Notice we can chain it because it's a Promise,
// this will run after completion of the promiseWhile Promise!
return message;
});
};


/**
* Enables public sharing on the given file object. then fetches its content.
*
* @param {Object} file A slack 'message.file' data object
* @param {string} token A slack API token that has 'files:write:user' scope
* @return {Promise<Object>} A Promise of the updated slack file data object
*/
BaseSlackHandler.prototype.enablePublicSharing = function (file, token) {
if (file.public_url_shared) return Promise.resolve(file);

this._main.incRemoteCallCounter("files.sharedPublicURL");
return rp({
method: 'POST',
form: {
file: file.id,
token: token,
},
uri: "https://slack.com/api/files.sharedPublicURL",
json: true
}).then((response) => {
if (!response || !response.file || !response.file.permalink_public) {
log.warn("Could not find sharedPublicURL: " + JSON.stringify(response));
return undefined;
}

return response.file;
});
}

/**
* Fetchs the file at a given url.
*
* @param {Object} file A slack 'message.file' data object
* @return {Promise<string>} A Promise of file contents
*/
BaseSlackHandler.prototype.fetchFileContent = function (file, token) {
if (!file) return Promise.resolve();

const url = getSlackFileUrl(file) || file.permalink_public;
if (!url) {
return Promise,reject("File doesn't have any URLs we can use.");
}

return rp({
uri: url,
resolveWithFullResponse: true,
encoding: null
}).then((response) => {
var content = response.body;
log.debug("Successfully fetched file " + file.id +
" content (" + content.length + " bytes)");
return content;
});
};

module.exports = BaseSlackHandler;
Loading

0 comments on commit 0a28929

Please sign in to comment.