Use common descriptions for mautrix bridges to improve consistency (#3914)
* Update docs for mautrix bridges: common section for extending the configuration Add links to the common guide for configuring mautrix bridges Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add the sections 'extending the configuration' Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add the common section "extending the configuration" based on docs for mautrix bridges Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: edit the top section Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: common section for setting up Double Puppeting Based on docs/configuring-playbook-bridge-mautrix-meta-instagram.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: common section for setting up Double Puppetting Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: replace duplicated descriptions for setting up Double Puppeting with a link to docs/configuring-playbook-bridge-mautrix-bridges.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: remove the section for setting up Double Puppeting The instruction has been described already in the section for prerequisites Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: add sections for enabling double puppeting Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: adopt common descriptions about bridge permissions Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-mautrix-whatsapp.md: remove description for relay-bot For WhatsApp the default relay mode is used and the description for it is available on the common guide for configuring mautrix bridges. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: remove descriptions about permissions in favor of the common one on docs/configuring-playbook-bridge-mautrix-bridges.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: remove a redundant instruction for referring to the section for troubleshooting The section is just below the instruction. Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: add notes about double puppeting with the Shared Secret Auth Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: remove redundant descriptions Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: remove links to the description about the relay mode from configuring-playbook-bridge-mautrix-bridges.md Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-mautrix-telegram.md: move the section for instruction about using the bridge for direct chat only Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-mautrix-bridges.md: add configuration for relay to an example of matrix_mautrix_SERVICENAME_configuration_extension_yaml Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: add a header for the reference to the common guide Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: adopt the common description for the section "Usage" Fix docs/configuring-playbook-bridge-mautrix-bridges.md: simplify the instruction to refer each documentation page (note that there are two formats of the links: https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html and https://docs.mau.fi/bridges/go/SERVICENAME/authentication.html) Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: edit anchor links to official documentation pages - Add links to the official documentation pages - Remove links to Hangouts' documentation page: the links have been replaced with ones to Google Chat bridge and the resources about Hangouts bridge have been removed - Replace links to documentation pages in python version with ones in go version Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add a note about variable names Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: re-add the section for instruction about appservice double puppeting Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> --------- Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara
GitHub
@ -1,14 +1,20 @@
|
||||
# Setting up Mautrix Whatsapp bridging (optional)
|
||||
|
||||
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
|
||||
|
||||
The playbook can install and configure [mautrix-whatsapp](https://github.com/mautrix/whatsapp) for you.
|
||||
|
||||
See the project's [documentation](https://docs.mau.fi/bridges/go/whatsapp/index.html) to learn what it does and why it might be useful to you.
|
||||
|
||||
## Prerequisite (optional)
|
||||
|
||||
### Enable Appservice Double Puppet or Shared Secret Auth
|
||||
|
||||
If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
|
||||
|
||||
For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
|
||||
See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
|
||||
|
||||
**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@ -20,19 +26,11 @@ matrix_mautrix_whatsapp_enabled: true
|
||||
|
||||
Whatsapp multidevice beta is required, now it is enough if Whatsapp is connected to the Internet every 2 weeks.
|
||||
|
||||
The relay bot functionality is off by default. If you would like to enable the relay bot, add the following to your `vars.yml` file:
|
||||
### Extending the configuration
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_whatsapp_bridge_relay_enabled: true
|
||||
```
|
||||
There are some additional things you may wish to configure about the bridge.
|
||||
|
||||
By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users add this to your `vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_whatsapp_bridge_relay_admin_only: false
|
||||
```
|
||||
|
||||
If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`.
|
||||
See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc.
|
||||
|
||||
## Installing
|
||||
|
||||
@ -55,26 +53,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
To use the bridge, you need to start a chat with `@whatsappbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
|
||||
### 💡 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 automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server 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
|
||||
|
||||
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 obtain one](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-Whatsapp` device some time in the future, as that would break the Double Puppeting feature
|
||||
You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/whatsapp/authentication.html).
|
||||
|
||||
Reference in New Issue
Block a user