diff --git a/docs/configuring-playbook-bridge-appservice-kakaotalk.md b/docs/configuring-playbook-bridge-appservice-kakaotalk.md index ad794a0bc..a25ada73c 100644 --- a/docs/configuring-playbook-bridge-appservice-kakaotalk.md +++ b/docs/configuring-playbook-bridge-appservice-kakaotalk.md @@ -17,17 +17,6 @@ matrix_appservice_kakaotalk_enabled: true You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation. -## Installing - -After configuring the playbook, run the [installation](installing.md) command: - -```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start -``` - -To make use of the Kakaotalk bridge, see [Usage](#usage) below. - - ### Additional configuration There are some additional things you may wish to configure about the bridge. @@ -37,10 +26,25 @@ Take a look at: - `roles/custom/matrix-bridge-appservice-kakaotalk/defaults/main.yml` for some variables that you can customize via your `vars.yml` file - `roles/custom/matrix-bridge-appservice-kakaotalk/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_appservice_kakaotalk_configuration_extension_yaml` variable +## Installing + +After configuring the playbook, run the [installation](installing.md) command: + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +## Usage + +Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). + +Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password. ### Set up Double Puppeting -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. #### Method 1: automatically, by enabling Shared Secret Auth @@ -59,12 +63,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - make sure you don't log out the `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature - - -## Usage - -Start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). - -Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password. - -After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so. diff --git a/docs/configuring-playbook-bridge-mautrix-discord.md b/docs/configuring-playbook-bridge-mautrix-discord.md index be5eb3969..5011bd586 100644 --- a/docs/configuring-playbook-bridge-mautrix-discord.md +++ b/docs/configuring-playbook-bridge-mautrix-discord.md @@ -25,17 +25,6 @@ matrix_mautrix_discord_enabled: true You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation. -## Installing - -After configuring the playbook, run the [installation](installing.md) command: - -```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start -``` - -To make use of the bridge, see [Usage](#usage) below. - - ### Additional configuration There are some additional things you may wish to configure about the bridge. @@ -45,31 +34,13 @@ Take a look at: - `roles/custom/matrix-bridge-mautrix-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file - `roles/custom/matrix-bridge-mautrix-discord/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_discord_configuration_extension_yaml` variable +## Installing -### Set up Double Puppeting - -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. - -#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - -#### Method 2: manually, by asking each user to provide a working access token - -**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature +After configuring the playbook, run the [installation](installing.md) command: +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` ## Usage @@ -97,3 +68,29 @@ To acquire the token, open Discord in a private browser window. Then open the de - send `guilds status` to see the list of guilds - for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire` 8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function. + +### Set up Double Puppeting + +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. + +#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth + +The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. + +Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. + +Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. + +#### Method 2: manually, by asking each user to provide a working access token + +**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). + +When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: + +- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md). + +- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` + +- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index 0741d9f6e..d5ac71789 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/docs/configuring-playbook-bridge-mautrix-facebook.md @@ -51,17 +51,27 @@ You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/c After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all` -## Set up Double Puppeting +## Usage -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. +You then need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -### Method 1: automatically, by enabling Shared Secret Auth +Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html). + +If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. + +### Set up Double Puppeting + +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. + +#### Method 1: automatically, by enabling Shared Secret Auth The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook. This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. -### Method 2: manually, by asking each user to provide a working access token +#### Method 2: manually, by asking each user to provide a working access token **Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). @@ -73,18 +83,6 @@ When using this method, **each user** that wishes to enable Double Puppeting nee - make sure you don't log out the `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature - -## Usage - -You then need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). - -Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account. You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/facebook/authentication.html). - -If you run into trouble, check the [Troubleshooting](#troubleshooting) section below. - -After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so. - - ## Troubleshooting ### Facebook rejecting login attempts and forcing you to change password diff --git a/docs/configuring-playbook-bridge-mautrix-googlechat.md b/docs/configuring-playbook-bridge-mautrix-googlechat.md index 505fecd41..cf6ad7ce0 100644 --- a/docs/configuring-playbook-bridge-mautrix-googlechat.md +++ b/docs/configuring-playbook-bridge-mautrix-googlechat.md @@ -16,32 +16,6 @@ matrix_mautrix_googlechat_enabled: true After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all` -## Set up Double Puppeting - -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. - -### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - - -### Method 2: manually, by asking each user to provide a working access token - -**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature - - ## Usage Once the bot is enabled you need to start a chat with `googlechat bridge bot` with handle `@googlechatbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). @@ -54,4 +28,29 @@ Once logged in, recent chats should show up as new conversations automatically. You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/googlechat/authentication.html). -After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so. +### Set up Double Puppeting + +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. + +#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth + +The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. + +Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. + +Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. + + +#### Method 2: manually, by asking each user to provide a working access token + +**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). + +When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: + +- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md). + +- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` + +- make sure you don't log out the `Mautrix-googlechat` device some time in the future, as that would break the Double Puppeting feature diff --git a/docs/configuring-playbook-bridge-mautrix-hangouts.md b/docs/configuring-playbook-bridge-mautrix-hangouts.md index 3a4a11736..f3fcb5c4e 100644 --- a/docs/configuring-playbook-bridge-mautrix-hangouts.md +++ b/docs/configuring-playbook-bridge-mautrix-hangouts.md @@ -18,30 +18,6 @@ matrix_mautrix_hangouts_enabled: true After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all` -## Set up Double Puppeting - -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. - -### Method 1: automatically, by enabling Shared Secret Auth - -The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook. - -This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - - -### Method 2: manually, by asking each user to provide a working access token - -**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). - -When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: - -- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md). - -- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - -- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature - - ## Usage Once the bot is enabled you need to start a chat with `Hangouts bridge bot` with handle `@hangoutsbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). @@ -54,4 +30,27 @@ Once logged in, recent chats should show up as new conversations automatically. You can learn more about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/hangouts/authentication.html). -After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so. +### Set up Double Puppeting + +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. + +#### Method 1: automatically, by enabling Shared Secret Auth + +The bridge will automatically perform Double Puppeting if you enable [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook. + +This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. + + +#### Method 2: manually, by asking each user to provide a working access token + +**Note**: This method for enabling Double Puppeting can be configured only after you've already set up bridging (see [Usage](#usage)). + +When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps: + +- retrieve a Matrix access token for yourself. Refer to the documentation on [how to do that](obtaining-access-tokens.md). + +- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` + +- make sure you don't log out the `Mautrix-Hangouts` device some time in the future, as that would break the Double Puppeting feature diff --git a/docs/configuring-playbook-bridge-mautrix-slack.md b/docs/configuring-playbook-bridge-mautrix-slack.md index 9065ec0b4..ba3281398 100644 --- a/docs/configuring-playbook-bridge-mautrix-slack.md +++ b/docs/configuring-playbook-bridge-mautrix-slack.md @@ -28,17 +28,6 @@ matrix_mautrix_slack_enabled: true You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation. -## Installing - -After configuring the playbook, run the [installation](installing.md) command: - -```sh -ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start -``` - -To make use of the bridge, see [Usage](#usage) below. - - ### Additional configuration There are some additional options you may wish to configure with the bridge. @@ -48,10 +37,27 @@ Take a look at: - `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file - `roles/custom/matrix-bridge-mautrix-slack/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_mautrix_slack_configuration_extension_yaml` variable +## Installing + +After configuring the playbook, run the [installation](installing.md) command: + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +``` + +## Usage + +1. Start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). +2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token. +3. The bot should respond with "Successfully logged into for team " +4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to. +5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication. ### Set up Double Puppeting -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. #### Method 1: automatically, by enabling Appservice Double Puppet @@ -70,12 +76,3 @@ When using this method, **each user** that wishes to enable Double Puppeting nee - send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE` - make sure you don't log out the `Mautrix-Slack` device some time in the future, as that would break the Double Puppeting feature - - -## Usage - -1. Start a chat with `@slackbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). -2. If you would like to login to Slack using a token, send the `login-token` command, otherwise, send the `login-password` command. Read [here](https://docs.mau.fi/bridges/go/slack/authentication.html) on how to retrieve your token and cookie token. -3. The bot should respond with "Successfully logged into for team " -4. Now that you're logged in, you can send a `help` command to the bot again, to see additional commands you have access to. -5. Slack channels should automatically begin bridging if you authenticated using a token. Otherwise, you must wait to receive a message in the channel if you used password authentication. diff --git a/docs/configuring-playbook-bridge-mautrix-twitter.md b/docs/configuring-playbook-bridge-mautrix-twitter.md index 6e3c82838..a31dcdf9e 100644 --- a/docs/configuring-playbook-bridge-mautrix-twitter.md +++ b/docs/configuring-playbook-bridge-mautrix-twitter.md @@ -18,22 +18,6 @@ matrix_mautrix_twitter_enabled: true After configuring the playbook, run the [installation](installing.md) command: `just install-all` or `just setup-all` -## Set up Double Puppeting - -If you'd like to use [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do), you have 2 ways of going about it. - -### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth - -The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. - -Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. - -Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. - -### Method 2: manually, by asking each user to provide a working access token - -This method is currently not available for the Mautrix-Twitter bridge, but is on the [roadmap](https://github.com/mautrix/twitter/blob/master/ROADMAP.md) under Misc/Manual login with `login-matrix` - ## Usage 1. You then need to start a chat with `@twitterbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). @@ -41,4 +25,20 @@ This method is currently not available for the Mautrix-Twitter bridge, but is on You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/python/twitter/authentication.html). -After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting), if you haven't already done so. +### Set up Double Puppeting + +After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do). + +To set it up, you have 2 ways of going about it. + +#### Method 1: automatically, by enabling Appservice Double Puppet or Shared Secret Auth + +The bridge will automatically perform Double Puppeting if you enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service or the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook. + +Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future. + +Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future. + +#### Method 2: manually, by asking each user to provide a working access token + +This method is currently not available for the Mautrix-Twitter bridge, but is on the [roadmap](https://github.com/mautrix/twitter/blob/master/ROADMAP.md) under Misc/Manual login with `login-matrix`