Bridging Slack.com #channels between companies
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
slackbridge
.gitignore Refactor slackbridge.py to wsgi.py. Add config loader classes. Aug 28, 2017
LICENSE.txt docs: Add GPLv3 license. Jan 27, 2016
Procfile Fixing Heroku Support Apr 22, 2018
README.rst Update README to RST. Update documentation. Aug 28, 2017
requirements.txt Update README to RST. Update documentation. Aug 28, 2017
runtime.txt Added envvar support for running on Heroku. Aug 25, 2017
sample.env Update README to RST. Update documentation. Aug 28, 2017
sample.ini
testconfig.py Refactor slackbridge.py to wsgi.py. Add config loader classes. Aug 28, 2017
wsgi.py errors: Quick and dirty timers Jun 1, 2018

README.rst

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.