Building Bridges

A Matrix setup with Synapse as the server and Element as the universal client is sufficient for secure internal communication and chats with other Matrix users. However, most users use other chat platforms – first and foremost, WhatsApp. One of the great strengths of Matrix is its bridges. These plugins let Synapse connect to other services like WhatsApp, Google Chat, Slack, Discord, and Telegram with bots (Figure 2). With a comprehensive Synapse setup, users only need a single Matrix client to handle all chats, regardless of the platform. The bridge setup is quite similar for many plugins, but I will look at what is probably the most important bridge as a representative example here: WhatsApp.

Figure 2: The Element desktop lists Matrix users and rooms, as well as Facebook, WhatsApp, and Slack users and groups. Users can control the functions of the bridges with the bridge bot.

The bridge runs as a standalone application, and it can theoretically run on a completely different computer than Synapse. In the setup discussed here, the mautrix-whatsapp bridge runs as a separate container with its own IP address (192.168.122.31) on the same system as Synapse. The plugin needs its own directory and database. As with Synapse, SQLite is fine for a trial run, but larger setups should use PostgreSQL. Create the /var/pods/mautrix_whats-app directory and start the plugin container:

podman run --rm --name mautrix_whatsapp --volume /var/pods/mautrix_whatsapp:/data:Z dock.mau.dev/mautrix/whatsapp:latest

When first launched, the bridge does not detect a configuration file. The container therefore creates a config.yaml with default settings in the specified directory and stops; you need to customize this file for your installation. The main entries for this setup are:

homeserver:
   address: http://192.168.122.26:8008
   domain: domain.com
appservice:
   address: http://192.168.122.31:29318
   hostname: 0.0.0.0
   port: 29318
   database:
     type: sqlite3
     uri: whatsapp.db

Additionally, you need to configure the permissions setting to match your domain so that only users from your domain are actively allowed to use the bridge:

permissions:
   "*": relay
   "domain.com": user
   "@admin:domain.com": admin

The plugin addresses the Synapse server directly over the internal address and provides its own service on the internal IP address of the container in return. In contrast to what the plugin documentation states, the database URL for SQLite contains only the filename of the database without the path and without sqlite:// at the beginning. The next time you start the container, include the IP information:

--net virt_net --ip 192.168.122.31 --mac-address 52:54:C0:A8:7A:1f

Again, if you are running your containers without a bridge network, set all addresses to 127.0.0.1, and instead of the network information, enter only the port -p 29318:29318.

When called for a second time, the plugin creates the database and checks the connection to the Synapse server. If the setup is OK, the mautrix-whatsapp bridge generates a registration.yaml and stops the container. This registration contains the plugin's access credentials for the Synapse server. Create a copy of the registration.yaml file in the Synapse server directory, preferably with the plugin name; that is:

cp /var/pods/mautrix_whatsapp/registration.yaml/var/pods/synapse/registration_whatsapp.yaml

Then, edit the configuration of the Synapse server in /var/pods/synapse/homeserver.yaml to include

app_service_config_files:
   - /data/registration_whatsapp.yaml

and restart the Synapse container. For each additional bridge plugin, you need to create a separate registration file and add it to the Synapse service in the same way. If you now start the mautrix-whatsapp container again (without --rm), it registers with the Synapse service and remains active as a bot from this point on. Other bridges (e.g., for Facebook Messenger or Slack) use an almost identical approach up to this point. However, the method of authenticating against a particular service will differ.

If you want to use the WhatsApp bridge, you need two things: a Matrix client like Element (preferably on the desktop) and your cell phone with the WhatsApp client. In Matrix, invite the WhatsApp bot @whatsappbot:domain.com to a chat. In the private chat room enter the commands for the bot – first of all, login. In response, the bot now sends a QR code. In the WhatsApp mobile app, go to Linked devices , and when you get there, select Add Device . Scan the QR code to allow the WhatsApp bot to access the chats; then, give the bot some time to read your WhatsApp configuration. By the way, the bot lists all functions if you type the help command.

The bot does not sync all your WhatsApp communication directly with Matrix. Instead, you can individually choose which private WhatsApp chats and rooms you want to synchronize. To add a group to Matrix, first list the available groups with the list groups bot command. The bot returns the list and a unique ID for each group. If you now enter open <group-ID> as the command, the bot will create a Matrix chat room to match the group. Everything you post there from your Matrix client will appear in WhatsApp exactly as if you were typing it directly into the WhatsApp client. You can create private chats with the pm <phone number> bot command to communicate with Matrix and WhatsApp users from the Element client. Of course, WhatsApp communication is then without the end-to-end encryption.

Conclusions

The basic setup of a chat infrastructure with Synapse takes some planning and time. In return, you can look forward to a secure communications platform beyond the established third-party providers. Thanks to the many bridges, Matrix allows communication with the popular chat networks.