From 9a75758bbe0668d3b46a19d6799cec5af5b6ae16 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Wed, 16 Oct 2024 00:35:07 +0900 Subject: [PATCH 1/6] Update docs/configuring-playbook-bridge-appservice-slack.md: fix indentation Signed-off-by: Suguru Hirahara --- ...guring-playbook-bridge-appservice-slack.md | 72 ++++++++++--------- 1 file changed, 39 insertions(+), 33 deletions(-) diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 6c2f830ee..7c40a4986 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -15,35 +15,35 @@ be done in Element by making a message, opening the options for that message and room ID will be displayed near the top. 2. Enable the bridge with the following configuration in your `vars.yml` file: -```yaml -matrix_appservice_slack_enabled: true -matrix_appservice_slack_control_room_id: "Your matrix admin room id" -``` + ```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: -``` + ``` /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). @@ -88,25 +88,31 @@ Note that the bot's domain is your server's domain **without the `matrix.` prefi * 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. + ``` + 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. 11. Unlinking Channels can be unlinked again like this: + ``` - unlink --room !the-matrix:room.id + unlink --room !the-matrix:room.id ``` Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again. @@ -117,12 +123,12 @@ Other configuration options are available via the `matrix_appservice_slack_confi `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. + 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 + Check you logs, if they say something like -`WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) ` + `WARN SlackEventHandler Ignoring message from unrecognised slack channel id : %s (%s) ` -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. + 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. From c7e347468f1b857acd3d1d9f352e9c88f8dd70a0 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Wed, 16 Oct 2024 00:40:43 +0900 Subject: [PATCH 2/6] Update docs/configuring-playbook-bridge-appservice-slack.md: fix line breaks Signed-off-by: Suguru Hirahara --- ...configuring-playbook-bridge-appservice-slack.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 7c40a4986..6ae5f7fb5 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -10,9 +10,8 @@ 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. +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: ```yaml @@ -37,6 +36,7 @@ room ID will be displayed near the top. 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: ``` @@ -119,16 +119,16 @@ room ID will be displayed near the top. ## 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. * 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) ` - 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. + 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. From bc579cd3ba566e13a18c737cd34bdafe0053c625 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Wed, 16 Oct 2024 00:42:09 +0900 Subject: [PATCH 3/6] Update docs/configuring-playbook-bridge-appservice-slack.md: fix list numbering --- ...nfiguring-playbook-bridge-appservice-slack.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 6ae5f7fb5..2582cb14a 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -35,9 +35,9 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 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. 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: +6. Invite the bridge bot user into the admin room: ``` /invite @slackbot:MY.DOMAIN @@ -45,7 +45,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 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 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 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 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se - 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,9 +75,9 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se **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. @@ -107,7 +107,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 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: From 45abdaac01b12fa1e2d5ea66ed861c9949e4f228 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Wed, 16 Oct 2024 00:47:48 +0900 Subject: [PATCH 4/6] Update docs/configuring-playbook-bridge-appservice-slack.md: fix capitalization Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bridge-appservice-slack.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 2582cb14a..52ceceb5c 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -119,9 +119,9 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se ## 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" +* 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. From f2a5b8595e95ae3c53766ace4440b02429ec747e Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Wed, 16 Oct 2024 00:56:41 +0900 Subject: [PATCH 5/6] Update docs/configuring-playbook-bridge-appservice-slack.md: use a common expression for adding configuration Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-bridge-appservice-slack.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 52ceceb5c..03aa50e8a 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -12,7 +12,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se 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: +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 From ba775a20fc0a05aaed87d499118f1cccf8798a3c Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Tue, 15 Oct 2024 19:44:28 +0300 Subject: [PATCH 6/6] Minor rewording --- docs/configuring-playbook-bridge-appservice-slack.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/configuring-playbook-bridge-appservice-slack.md b/docs/configuring-playbook-bridge-appservice-slack.md index 03aa50e8a..c837276eb 100644 --- a/docs/configuring-playbook-bridge-appservice-slack.md +++ b/docs/configuring-playbook-bridge-appservice-slack.md @@ -10,7 +10,7 @@ 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. +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. 2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.DOMAIN/vars.yml` file: @@ -81,7 +81,7 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se * 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//details/`. @@ -123,12 +123,12 @@ loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Se * 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. + 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) ` + `WARN SlackEventHandler Ignoring message from unrecognised Slack channel id : %s (%s) ` 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.