Skip to content
This repository has been archived by the owner on Apr 19, 2022. It is now read-only.


Repository files navigation


Support room on Matrixdonate


This is a slack puppeting bridge for matrix. It is based on mx-puppet-bridge and provide multi-user instances.

Quick start using Docker

Docker image can be found at

For docker you probably want the following changes in config.yaml:

bindAddress: ''
filename: '/data/database.db'
file: '/data/bridge.log'

Also check the config for other values, like your homeserver domain.

Install Instructions (from Source)

  • Clone and install:
    git clone
    cd mx-puppet-slack
    npm install
  • Edit the configuration file and generate the registration file:
    cp sample.config.yaml config.yaml
    # fill info about your homeserver and Slack app credentials to config.yaml manually
    npm run start -- -r # generate registration file
  • Copy the registration file to your synapse config directory.
  • Add the registration file to the list under app_service_config_files: in your synapse config.
  • Restart synapse.
  • Start the bridge:
    npm run start
  • Start a direct chat with the bot user (@_slackpuppet_bot:domain.tld unless you changed the config). (Give it some time after the invite, it'll join after a minute maybe.)
  • Get your Slack tokens as below, and tell the bot user to link your workspaces:
    link MYTOKEN (see below for details)
  • Tell the bot user to list the available rooms: (also see help)
    Clicking rooms in the list will result in you receiving an invite to the bridged room.

How to get Slack app credentials

Option 1. Legacy Token

Get a legacy token from and then chat with the bot user (@_slackpuppet_bot:domain.tld unless you changed the config):

link <token>

Option 2. OAuth

To use OAuth

  1. Set up a Slack app at You do not need to setup any of the additional features or functionality that Slack prompts you to enable when you create a new Slack app.
  2. Go to the "OAuth & Permissions" tab in the sidebar
  3. Add your redirect URL.
  4. Fill in the oauth block in your config.yaml file. Be sure to forward the oauth.redirectUri to the bridge.
  5. Start a chat with the bot user (@_slackpuppet_bot:domain.tld unless you changed the config)
  6. Tell the bot: link
  7. Click the link it gives and allow access
  8. Copy the token given and send the bot that token with: link TOKEN_YOU_COPIED

Option 3. xoxs token

Warning:: Linking your xoxs account's token is against Slack's Terms of Service.

First you must retrieve your xoxs token: Go to your slack customization page, e.g., and then open the debugging console (F12 or rightclick --> inspect element). Get the token by entering TS.boot_data.api_token.

After that, run:

link <token>

Option 4. xoxc token

Warning: Linking your xoxc account's token is against Slack's Terms of Service.

First you must retrieve your xoxc token: In the network manager, filter for type WS/WebSocket, and the xoxc token is there as URL parameter of that request.

Next you will need to get the contents of your d cookie.

After that, run:

link <token> <d cookie contents>


It is also possible to use mx-puppet-slack as a relay. For that, the events API needs to be configured. in slack.path you can configure the base-path for the various new endpoints. By default this is /_matrix/slack/client.

The events API will have appended /events, so by default /_matrix/slack/client/events.

The new oauth endpoint to add the slack bot to new teams has /oauth/{appId} appended, so by default /_matrix/slack/client/events/{appId}.

Create your slack app, give it the permissions and then link it with link <appId> <clientId> <clientSecret> <signingSecret>. Don't forget to settype <puppetId> relay!