I’ve previously written a post on getting riot and matrix working on a homelab environment. The point of the post was a starting ground for creating a central hub for bringing in the different chat apps into a single interface.

Previous Post

What am I doing?

Using the extensibility of Matrix through bridges the project is to link my home-hosted Matrix server to the services and provide myself with a single Riot interface on my phone and web browser for messaging.


This was the first bridge I installed and it works by using the WhatsApp Web interface, so needs WhatsApp installed on a device and running to receive messages. If you really don’t want to run WhatsApp on your phone the Git page has instructions on getting Whatsapp running on an AndroidVM.

For the purposes of these instructions, I’m only going down the route of linking the bridge to WhatsApp running on my phone. I will get the VM working later.

Config Setup

Create a directory for the bridge and cd into it:

mkdir mautrix-whatsapp && cd mautrix-whatsapp

N.B. The docker image will chown its /data directory to UID 1337. The commands below mount the working directory as /data, so make sure you always run them in the correct directory.

Run the container for the first time, so it can create a config file for you:

docker run --rm -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest

open the configuration file and change the following lines to reflect your setups

nano config.yaml

Change the lines for the homeserver

homeserver:  address: https://matrix.mydomain.com  domain: matrix.mydomain.com

Change the permissions section to reflect the user you login to your riot server with and the domain.

  permissions:    '*': 5    '@myriotuser:matrix.mydomain.com': 100    matrix.mydomain.com: 10

save and exit

Run the docker command again to generate the registration.yaml

docker run --rm -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest

The registration.yaml needs editing and the line

url: http://localhost:29318

changed to

url: http://<docker ip address>:29318

You can find the ip of the container using

docker inspect <container id>

Next copy the registration.yaml to the location of the synaps config

sudo cp registration.yaml /var/lib/docker/volumes/synapse-data/_data/

Then change the rights of the file

sudo chown 991:991 /var/lib/docker/volumes/synapse-data/_data/registration.yamlsudo chmod 644 /var/lib/docker/volumes/synapse-data/_data/registration.yaml

edit the homeserver.yaml used by the Synapse Server

app_service_config_files:   - data/registration.yaml

Then restart the Synapse Docker container

Once restarted run the Whats App docker image

docker run -d --restart unless-stopped -p 29318:29318 -v `pwd`:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest


Login to Riot

Create a new Room (MyWhatsApp)

/invite @whatsappbot:matrix.mydomain.com

you should see

WhatsApp bridge botThis room has been registered as your bridge management/status room. Send `help` to get a list of commands.



Log in by scanning the QR code. If the code expires before you scan it, the bridge will send an error to notify you.

  1. Open WhatsApp on your phone.
  2. Tap Menu or Settings and select WhatsApp Web.
  3. Point your phone at the image sent by the bot to capture the code.

Finally, the bot should inform you of a successful login and the bridge should start creating portal rooms for your recent WhatsApp groups and private chats.


A Matrix-WhatsApp puppeting bridge. Contribute to tulir/mautrix-whatsapp development by creating an account on GitHub.
A Matrix-WhatsApp puppeting bridge. Contribute to tulir/mautrix-whatsapp development by creating an account on GitHub.
Android VM setup

By davidfield

Tech Entusiast