I started running a WhatsApp Mautrix Bridge to connect an otherwise unused phones WhatsApp to my conduit matrix server.

Why

Read the background here.

My goal has been to offer to my family a way to take part in WhatsApp communications without the need to share their numbers or even have a phone.

How

An old Sony Z1 with Carbon ROM didn't work and I switched to an also old Sony Z3c with broken touch to use a phone with a stock rom.

Mautrix Bridge documentation

Reading the documentation I had the feeling it describes something I was supposed to know already.

I found it difficult to understand the terms puppeting and relay and searched around the web to find information about them.

Terms

puppeting

Imagine your Matrix server is the player and uses a puppet to tell you a story. This puppet is the WhatsApp you connect your bridge to.

Actually the Bridge is puppeting and does get its story from the Matrix server: When there's a message in a bridged room it takes it, uses its WhatsApp puppet and tells it to the connected WhatsApp contact or group.

double it - double puppeting

The other way around the player is the WhatsApp side and it plays stuff back.

When bridging I'd think that everything works in both ways anyway, but it's not like that.

The Bridge needs permissions to remote controll the WhatsApp side (the single puppeting that is standard for the bridge) and it needs for some actions permissions to manipulate the Matrix side (the other direction - the double).

Configuring double puppeting means to give the Bridge additional permissions on the matrix side to be able to do stuff there.

This is achived through a second, different app service that needs to be registered to the matrix server.

interlude

With puppeting the bridge has the ability to relay messages between a WhatsApp group or contact and a matrix room that is a direct chat.

It is meant to relay messages for one matrix account that is joined into that room.

Inviting other matrix accounts to such a bridged room is not possible.

To do that you'll need a…

relay

If relay mode is configured it's possible to invite other matrix accounts into a room that is bridged to WhatsApp.

The bridged matrix account becomes a bot: it will take any message from the room, prepend it with whatever is configured in the bridge configuration and send it to the WhatsApp side of the bridge.

To make use of this it is recommended to create its own matrix account for the relay bot. When sharing a family WhatsApp account this makes it possible for different persons to participate in different groups or chat with different contacts.

Howto

After understanding a bit of the context and terms I found it quite easy to follow the setup instructions.

In my setup I use #conduit on a #yunhost as a matrix server.

The yunohost app showed that I'd need more memory than I have left on my yunohost so I installed on a small SBC and used the docker image.

It is a good idea to start with creating the matrix account for the user that is supposed to relay if relaying should be used.

Throughout the installation instructions this account should be used on the matrix side.

pitfalls

double_puppet_server_map

In my setup the bridge connects to http://<private-IP>:<port>, because it can't reach my matrix server by its name.

Both hosts (conduit-host and mautrix-bridge-host, two different computers) are on a private subnet of their own and the secure in https didn't make sense.

I could have opted for hairpinning or to let the resolver on the bridge-host find the internal IP of the matrix server, but I wanted to avoid complexity and unnecessary encryption/decryption.

For homeserver this is explained in the manual.

When I configured double puppeting I didn't understand what the url and domain is used for and put the domain and url containing the hostname there.

Later I found that I'd need to change the url to the same settings as under homeserver. On the matrix channel about the bridge someone told me that they hadn't configured the setting at all and it worked (maybe it falls back to the homeserver settings).

needed to change the matrix account

When I realized how relay mode works I needed to change the matrix account from my own one to a relay account.

To get stuff working again I had to:

• logout with the other user from the WhatsApp session
• delete the association with the bridge in WhatsApp
• stop the bridge, delete the database and start the bridge
• login using the new relay account to my WhatsApp

After doing all this history of groups got loaded again and all the contacts opened appeared for the relay account automatically.