Skip to content

Latest commit

 

History

History
161 lines (122 loc) · 5.38 KB

README.rst

File metadata and controls

161 lines (122 loc) · 5.38 KB
Raw

SlackBridge

SlackBridge bridges Slack.com #channels between companies.

  • Does your company use Slack?
  • Does your customer/subcontractor also use slack?

Then, no more hard times of having to grant each others' workers access on both Slack teams: you can now form a union between two of your Slack #channels using this bridge.

Configuration and setup

You'll need to run this as a daemon on a publicly reachable IP:

  • Test it in the foreground from the command line, to get a poor mans builtin http server. You can use the nginx proxy_pass directive (without path) to reach it.
  • Run it as a WSGI application. Has been tested with uWSGI; you can use the nginx uwsgi_pass directive to reach it. Multiple workers are allowed, as long as it is single-threaded.

Configuration in Slack:

  • Create at least one Incoming WebHook per Slack team; record the URL. (Tip: set the other relation's brand logo as default icon, or a generic :speech_balloon: icon if you use it for multiple channels.)
  • For each #channel that you want to bridge/share, create an Outgoing WebHook, record the token. Set the WebHook POST URL to where this bridge is reachable from the world, and append /outgoing to the path.
  • And, preferably, you'll also need at least one WebAPI token to supply some info to the other end. You can do this by creating a bot user (call it @slackbridge). Record the API token. (Previously, the recommended token was a "user token", which is now legacy.)

Inifile configuration:

Configuration using an inifile would look like this (skip if you're using Heroku):

[yourcompany-othercompany]
A.webhook_out_token = <the-recorded-token>
A.webhook_in_url = <the-recorded-url>
A.channel = #<channel-you-wish-to-share>
A.peername = othercompany
A.webapi_token = <xoxb-bot-token-goes-here>

The other side of the SlackBridge has to do the same "Configuration in Slack" steps as seen above. Those values should go into a second set of key-value pairs, starting with B:

B.webhook_out_token = <the-peers-recorded-token>
B.webhook_in_url = <the-peers-recorded-url>
B.channel = #<channel-they-wish-to-share>
B.peername = yourcompany
B.webapi_token = <xoxb-their-bot-token-goes-here>

The inifile will be searched as ./slackbridge.ini or in the location supplied by the SLACKBRIDGE_INIFILE environment variable.

You can add extra sections for more bridges. See the sample.ini example configuration for more details.

Environment variable (Heroku style) configuration:

Instead of doing inifile config, you can use environment variables.

In that case, instead of the A and B config as seen above, you'd set these for both A and B:

PORTAL_1_SIDE_A_WEBHOOK_OUT_TOKEN=
PORTAL_1_SIDE_A_WEBHOOK_IN_URL=
PORTAL_1_SIDE_A_CHANNEL_NAME=
PORTAL_1_SIDE_A_GROUP_NAME=
PORTAL_1_SIDE_A_WEB_API_TOKEN=

You can increment the number 1 for more bridges. See the sample.env example configuration for more details.

Inner workings

The SlackBridge works like this:

  • The Slack Outgoing WebHook -- from both teams -- posts messages to the slackbridge on the supplied /outgoing URL.
  • The bridge posts the message to a subprocess, so the main process can return immediately.
  • The subprocess translates the values from the Outgoing WebHook to values for the Incoming WebHook, optionally overwriting the #channel name and some other translations (channel name, avatars, @mentions).
  • The translated values get posted to the Incoming WebHook URL so they end up on the other end of the bridge.

Supported commands by the bot -- type it in a bridged channel and get the response there:

  • !info lists the users on both sides of the bridge. Now you know who you can @mention.

Heroku

These instructions require Heroku Command Line:

heroku create
cp sample.env .env
# Properly set all environment variables in file
vim .env
# Test running the bridge locally
heroku local
# Push environment variables to Heroku
heroku config:push --overwrite
# Deploy to Heroku
git push heroku <my-branch>

Things to note:

  • Free Heroku dynos can only run 18 hours per day. After that, the slack bridge will simply not work. This can be very confusing. You may wish to consider paying $7/month for a 24h dyno.
  • Please see sample.env for an example of how to set environment variables.

BUGS / CAVEATS

  • You can skip the WebAPI token, but @mentions will look awkward and !info won't give you all the info.
  • Message edits and snippet/file/image uploads will not get sent across the bridge.

TODO

  • Clean up code (ugly globals). Too few subclasses.
  • Make more extensible. You may want to integrate your own slackbot-style responses here.
  • Add default icon to CONFIG, so we can reuse the same incoming webhook for more than one team, even if they don't supply the wa_token.
  • Clean up the config. It's a horrible mess as it is.