Slackline: a bot to bridge channels between *free* Slack workspaces
=========

Slackline features
------------------

System                    Slackline       42wim/matterbridge   ossobv/slackbridge   atomic-app/slack-portals
                        +----------------+--------------------+-------------------+--------------------------+
Workspace presence      | Bot user       | Classic bot user   | Legacy Webhooks   | Legacy Webhooks          |
Configuration           | Env variables  | File (TOML)        | File or env vars  | Graphical Web portal     |
Persistence             | PostgreSQL     | ✗                  | ✗                 | SQLite (config only)     |
                        +----------------+--------------------+-------------------+--------------------------+
Message appearance      | Name & avatar  | Username & avatar  | Username & avatar | Username & avatar        |
User mentions           | ✓ (spellcheck) | Internal username  | Internal username | ✗                        |
List users              | Slash command  | ✗                  | !info message     | ✗                        |
Edits and deletions     | ✓              | Until next restart | ✗                 | ✗                        |
Emoji reactions         | ✗ (warns user) | ✗                  | ✗                 | ✗                        |
Emoji in messages       | ✓              | ✓                  | ✓                 | ✓                        |
File attachments        | ✗ (warns user) | ✓                  | ✗ (warns user)    | ✗                        |
Typing notification     | ✗              | Unattributed       | ✗                 | ✗                        |
                        +----------------+--------------------+-------------------+--------------------------+
Threaded messages       | ✓              | Until next restart | ✗                 | ✗                        |
Thread broadcasts       | ✓              | ✗                  | N/A               | N/A                      |
Message pinning         | ✗              | ✗                  | ✗                 | ✗                        |
Channel topics          | ✗              | ✓                  | ✗                 | ✗                        |
                        +----------------+--------------------+-------------------+--------------------------+
Public channels         | ✓              | ✓                  | ✓                 | ✓                        |
Private channels        | ✓              | ✓                  | ✗                 | ✗                        |
Direct messages         | One-on-one     | ✗                  | ✗                 | ✗                        |
Other platforms         | ✗              | ✓                  | ✗                 | ✗                        |
                        +----------------+--------------------+-------------------+--------------------------+
License                 | GPLv3          | Apache 2.0         | GPLv3             | MIT                      |
Implementation language | JavaScript     | Go                 | Python            | Ruby on Rails            |
                        +----------------+--------------------+-------------------+--------------------------+

User instructions
-----------------

Most functions work as they would in vanilla Slack, with a few exceptions:
 * To tag someone the other side of a bridged channel, enclose the mention in backticks ("code"):
   `@Their Name`
  - If you forget to do this or misspell the person's name, the bot will send you a private inline
    ("ephemeral") message pointing out the error and (in the latter case) listing bridged members.
  - Because the Slack interface doesn't know bridged members, names will not complete as you type.
  - The slash command lets you to list people without looking silly. Assuming it's named /slackline:
    /slackline list
  - If trying to send a message ending in a mention, you may need to click just to the right of the
    message text or press the right arrow key just before sending to prevent Slack from mangling it.
 * If you mention a user who is in your own workspace, on the same side of a bridged channel, the
   @Their Name mention will appear as `@Their Name` on the other side of the bridge, as if they had
   been remotely mentioned from there.
  - If you mention someone who is in your own workspace but not the bridged channel, the mention
    will be visible but redacted on the other side of the bridge. Hovering over it with a mouse will
    show "Private user info."
  - If after the above, you accept Slack's suggestion to add them to the channel, any subsequent
    mentions from either side of the bridge will be treated normally.
  - As soon as someone leaves a channel, subsequent mentions made from the same workspace are
    redacted and it becomes impossible to mention them remotely from the bridged workspace.
  - If you mention another channel from your own workspace, it will be visible but redacted on the
    other side of the bridge. Hovering over it with a mouse will show "Private channel info."
 * Because the bridge only has access to a single bot user per Slack workspace, it does not support
   reactions: it would be impossible to tell who had made each reaction and how many times it had
   been given. The bot will send you a warning message if you do react in a bridged channel.
  - As a workaround, you can send emoji in messages instead.
  - If you send an emoji that isn't present in the bridged workspace, it will appear as the text
    :emoji-name:. Likewise, the other side can use it by typing that same name.
 * If you send a nonempty message with file attachment(s), the text is relayed to the other side of
   the bridge but attachments are dropped. The bot sends you a warning whenever it drops an
   attachment in this way.
 * You can DM a user on the other end of a bridged channel. Assuming the slash command /slackline:
   /slackline dm Their Name
  - Resulting messages will appear in a single DM channel with the bot user, mixed with DMs with
    other bridged users. You manage the person you're currently DM'ing using the slash command.
  - In addition to temporary (ephemeral) help messages, the bot leaves permanent messages showing
    changes in destination so you can understand the chat log when you read it later.
  - If you DM the bot without first using the slash command, it will send you a temporary help
    message and react to your post with a warning emoji so you can tell it wasn't sent. You may
    safely delete the message from your DMs if you like.
  - If you respond to a DM in a thread, your response will automatically be routed to the user that
    message was shared by or with. In addition, the destination for further DMs will be changed in
    case you decide to continue the conversation outside the thread; the bot will warn you of this.
  - When DM'ing less savvy users, you may wish to advise them in the message to reply in a thread.
 * Depending on how the server is hosted, you may see the following Slackbot message when using the
   slash command if no bridged channel has been used for a while:
   failed with the error "operation_timeout"
  - If this happens, simply wait a few seconds and hit enter to rerun your command. If the problem
    persists after a few tries, you'll want to contact your admin.
 * Note that you cannot use the slash command within threads, only channels. Furthermore, using it
   anywhere except a bridged channel or your DMs requires specifying the channel in question.
  - For more details, check the inline usage documentation:
    /slackline help

Setup instructions (for admins)
-------------------------------

Launch the server:
 1. If persistence is desired (required for production), set up a PostgresSQL database.
 2. To enable persistence so threading, editing, and deletion work after a restart, export variable:
    $ export DATABASE_URL=postgres://<path>
 3. Start the server by executing:
    $ PORT=<port> npm start
 4. Take note of the fully-qualified URL and port at which you are running the server.

For each workspace you want to bridge, do the following:
 1. Navigate to https://api.slack.com/apps and hit Create New App.
 2. Choose an App Name (e.g., Slackline) and select the workspace.
 3. Under Display Information, customize the appearance of the bot user.
 4. Under Features in the sidebar, click Event Subscriptions.
 5. Toggle the Enable Events slider to On.
 6. Enter the URL of your server under Request URL.
 7. Expand Subscribe to bot events and add all of the following:
    message.channels, message.groups, message.im, member_joined_channel, member_left_channel, reaction_added
 8. Click the Save Changes button at the bottom.
 9. Under Features in the sidebar, click Slash Commands, then hit Create New Command.
10. Set Command as you prefer (e.g., slackline) and Short Description to anything at all.
11. Reenter your same server URL in Request URL.
12. Check the box labeled Escape channels, users, and links sent to your app and hit Save.
13. Repeat for each desired command abbreviation/alias.
14. Under Features in the sidebar, click OAuth & Permissions.
15. Leave channels:read and groups:read selected and grant all of the following further permissions:
    chat:write.customize (and chat:write), im:read, team:read, users:read, reactions:write
16. Under Features in the sidebar, click App Home.
17. Make sure Messages Tab is enabled, then further customize the bot's appearance, e.g.:
    Display Name (Bot Name), Always Show My Bot as Online
18. Under Settings in the sidebar, click Install App.
19. Click the Install to Workspace button and hit Allow on the confirmation screen.
20. Once back at Installed App settings, copy the Bot User OAuth Access Token to your clipboard.

Configure the server by updating its environment as follows:
 1. For each (zero-indexed) workspace you want to connect to, export an environment variable:
    $ export TOKEN_<index>=<subdomain>#<secret>
 2. For each (uni-directional) channel broadcast bridge, export an environment variable:
    $ export LINE_<workspace>_<channel>=<workspace>#<channel>
 3. For the best tested configuration, configure the opposite direction of each bridge as well.
 4. Restart the server.

For each workspace, give the bot user access to each channel you configured above:
 1. Navigate to https://<subdomain>.slack.com and one of the channels in question.
 2. Press the Show channel details button in the upper-right corner.
 3. In the right-hand sidebar, click More, choose Add apps, and find your newly-created app.
 4. Repeat these steps for each other channel in the workspace.

Supported configurations (for admins)
-------------------------------------

 * Channels may be bridged within the same workspace or between different ones.
  - If any channel in a workspace is bridged with a channel in the same workspace, it becomes
    possible to DM local Slack users via Slackline. This is probably not useful except for testing.
 * If a channel is bridged in one direction only, messages within the destination side stay there;
   the bot does not send warnings when such messages are (not) sent, so the fact that the channel is
   configured in this way is apparent only to users with access to both sides of the bridge.
  - The most natural use of this is to allow users from a remote workspace to make announcements in
    a #general channel that has restricted posting (and probably threaded replying) permissions.
  - The configuration can also be used to "eavesdrop" on one or more channels from a "monitoring"
    one. Possible use cases include compliance, transparency, observer membership of a committee, or
    achiving (although note that deletions and edits in the source channel will propagate as usual).
  - If used between multiple workspaces, this could allow a single user to centralize notifications
    they care about (e.g., to minimize open workspaces or account logins from their mobile device).
  - It is perhaps also useful for collecting information from multiple channels for a bot to use.
 * Note that DM'ing is only supported between channels that are bridged bidirectionally. Use in
   other configurations is at your own peril.
  - It is possible, though perhaps undesirable, to bridge a channel with itself. Such a pairing is
    inherently bidirectional, and therefore allows any channel member to DM any other via Slackline.
 * Users are only permitted to DM with each other if each is a member of the opposite side of a
   bridged channel pair.
  - The slash command will inform users when they explicitly specify a channel they are not a member
    of. Note that this feature presents an intentional side channel: a user can use it to determine
    whether a private channel is bridged given its name, or determine the name of bridged channels
    via bruteforce. As a result, channel names should not be considered secret; in practice, they
    are not anyway if users are allowed to create new channels.
  - If either party of an existing DM conversation is removed from their side of the bridged channel
    pair, both are notified that they cannot continue the conversation. Note, however, that any
    edits or deletions of existing messages still propagate; this is in case it is desirable to
    remotely delete DMs that had been shared with a bridged member before the mods on the remote
    side banned them from the channel.
  - If a since-unbridged user is harassing another by editing existing DMs, the admin's primary
    recourse is to drop the corresponding message pairings from the Slackline database.
 * Note that Slackline does not propagate any bot messages, even those sent by other bots.