mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2024-12-23 04:55:46 +00:00
Merge pull request #3606 from luixxiul/fix
Update docs/configuring-playbook-bridge-appservice-slack.md
This commit is contained in:
Slavi Pantaleev
GitHub
commit
cf50800b30
@ -10,42 +10,42 @@ See the project's [documentation](https://github.com/matrix-org/matrix-appservic
|
||||
|
||||
loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
|
||||
|
||||
1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can
|
||||
be done in Element by making a message, opening the options for that message and choosing "view source". The
|
||||
room ID will be displayed near the top.
|
||||
2. Enable the bridge with the following configuration in your `vars.yml` file:
|
||||
1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can be done in Element by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
|
||||
|
||||
```yaml
|
||||
matrix_appservice_slack_enabled: true
|
||||
matrix_appservice_slack_control_room_id: "Your matrix admin room id"
|
||||
```
|
||||
2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_appservice_slack_enabled: true
|
||||
matrix_appservice_slack_control_room_id: "Your matrix admin room id"
|
||||
```
|
||||
|
||||
3. Enable puppeting (optional, but recommended)
|
||||
|
||||
```yaml
|
||||
matrix_appservice_slack_puppeting_enabled: true
|
||||
matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
|
||||
matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
|
||||
```
|
||||
```yaml
|
||||
matrix_appservice_slack_puppeting_enabled: true
|
||||
matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
|
||||
matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
|
||||
```
|
||||
|
||||
4. Enable Team Sync (optional)
|
||||
|
||||
```yaml
|
||||
matrix_appservice_slack_team_sync_enabled: true
|
||||
```
|
||||
```yaml
|
||||
matrix_appservice_slack_team_sync_enabled: true
|
||||
```
|
||||
|
||||
See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
|
||||
|
||||
4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
|
||||
5. Invite the bridge bot user into the admin room:
|
||||
5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
|
||||
|
||||
```
|
||||
6. Invite the bridge bot user into the admin room:
|
||||
|
||||
```
|
||||
/invite @slackbot:MY.DOMAIN
|
||||
```
|
||||
```
|
||||
|
||||
Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
|
||||
Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
|
||||
|
||||
6. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
|
||||
7. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
|
||||
|
||||
Name the app "matrixbot" (or anything else you'll remember).
|
||||
|
||||
@ -53,7 +53,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
|
||||
|
||||
Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
|
||||
|
||||
7. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
|
||||
8. Click on Event Subscriptions and enable them and use the request url `https://matrix.DOMAIN/appservice-slack`. Then add the following events and save:
|
||||
|
||||
Bot User Events:
|
||||
|
||||
@ -63,7 +63,7 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
|
||||
- reaction_added
|
||||
- reaction_removed
|
||||
|
||||
8. Click on OAuth & Permissions and add the following scopes:
|
||||
9. Click on OAuth & Permissions and add the following scopes:
|
||||
|
||||
- chat:write:bot
|
||||
- users:read
|
||||
@ -75,36 +75,42 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi
|
||||
|
||||
**Note**: 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 than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
|
||||
|
||||
9. Click on Install App and Install App to Workspace. Note the access tokens shown. 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.
|
||||
10. Click on Install App and Install App to Workspace. Note the access tokens shown. 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.
|
||||
|
||||
10. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
|
||||
11. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
|
||||
|
||||
* 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.
|
||||
|
||||
* Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for slack and `/invite @slackbot:MY.DOMAIN` for matrix.
|
||||
* Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:MY.DOMAIN` for Matrix.
|
||||
|
||||
* Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel id>/details/`.
|
||||
|
||||
* 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
|
||||
```
|
||||
|
||||
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
|
||||
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
|
||||
|
||||
11. Unlinking
|
||||
12. Unlinking
|
||||
|
||||
Channels can be unlinked again like this:
|
||||
|
||||
```
|
||||
unlink --room !the-matrix:room.id
|
||||
```
|
||||
@ -113,16 +119,16 @@ Other configuration options are available via the `matrix_appservice_slack_confi
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
* as always, check the logs:
|
||||
`journalctl -fu matrix-appservice-slack`
|
||||
* As always, check the logs: `journalctl -fu matrix-appservice-slack`
|
||||
|
||||
* linking: "Room is now pending-name"
|
||||
This typically means that you haven't used the correct slack channel id. Unlink the room and recheck 'Determine the "channel ID"' from above.
|
||||
* Linking: "Room is now pending-name"
|
||||
|
||||
This typically means that you haven't used the correct Slack channel id. Unlink the room and recheck 'Determine the "channel ID"' from above.
|
||||
|
||||
* Messages work from M to S, but not the other way around
|
||||
Check you logs, if they say something like
|
||||
|
||||
`WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) <the channel id> <some other id>`
|
||||
Check you logs, if they say something like
|
||||
|
||||
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link
|
||||
your room multiple times without unlinking it after each failed attempt.
|
||||
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel id : %s (%s) <the channel id> <some other id>`
|
||||
|
||||
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user