What are Matrix Bridges?

Matrix is an open protocol that is interoperable with other messaging platforms using an Open Standard. Connection to the other platforms is so-called Bridging.

There are different types of bridges allowing Matrix to interconnect with systems such as XMPP, IRC, Signal, iMessage, Telegram, WhatsApp, … Refer to the official page for more information.

The following tutorial gives the step-by-step installation of Bridge to WhatsApp with the Docker image tulir/mautrix-whatsapp.

Bridging Matrix to WhatsApp requires:

  • creation of a database dedicated to the bridge
  • installation of mautrix-whatsapp Docker container
  • modification of Synapse homeserver configuration file
  • enabling WhatsApp Web mode

 

Step-by-step installation

Creation of mautrix-whatsapp database on the same postgres server used by Matrix

  1. the easiest way to create a new database is using pgadmin4, an open source management platform for PostgreSQL
    1. download dpage/pgadmin4 Docker image
    2. create the container by launching the downloaded image with following parameters:
    1. add following Environment Variables:
      • PGADMIN_DEFAULT_EMAIL: EMAIL_FOR_PGADMIN_LOGIN
      • PGADMIN_DEFAULT_PASSWORD: PWD_FOR_PGADMIN_LOGIN
      • ENHANCED_COOKIE_PROTECTION: True
    1. run pgadmin4 container
    2. connect to http://host_server_IP_address:YOUR_PGADMIN_PORT (the port defined at pgadmin4 installation above) with the credentials configured in the Postgres container Environment Variables
    1. right click on Login/Group Role and create a new user YOUR_MAUTRIX_WHATSAPP_USER (in General tab) / YOUR_MAUTRIX_WHATSAPP_PWD (in Definition tab) with following privileges:
    1. right click on Databases and create a new DB called mautrix_whatsapp owned by user you just created ( YOUR_MAUTRIX_WHATSAPP_USER)
Second step is installation of tulir/mautrix-whatsapp Docker image. Rather than using the Synology Docker GUI, let’s use CLI.
  1. installation of mautrix-whatsapp Docker image
    1. open a terminal and ssh to your Synology
    2. get root privileges: sudo su –
    3. download the Docker image: docker pull dock.mau.dev/tulir/mautrix-whatsapp:latest
    4. create docker/mautrix-whatsapp folder
    5. in order to create default config.yaml and registration.yaml files, run the image:
docker run --rm -v /volume1/docker/mautrix-whatsapp/:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest
    1. Modify the config.yaml:
homeserver:
  address: https://your_matrix_server_name
  domain: your_matrix_server_name
appservice:
  address: http://host_server_IP_address:29318
  hostname: host_server_IP_address
  port: 29318
  database:
    type: postgres
    uri: postgres://YOUR_MAUTRIX_WHATSAPP_USER:YOUR_MAUTRIX_WHATSAPP_PWD@your_host_server_IP_address:15432/mautrix-whatsapp_DB_name?sslmode=disable
    max_open_conns: 20
    max_idle_conns: 2
 permissions:
    '*': relaybot
    '@user:your_matrix_server_name': admin
    'your_matrix_server_name': user
    1. to create the registration.yaml file, run again the image:
docker run --rm -v /volume1/docker/mautrix-whatsapp/:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest
    1. copy the registration.yaml file to synapse folder (you can also rename it to whatsapp-registration.yaml in case you want to install multiple bridges to different platforms)
  1. update Synapse homeserver.yaml file and restart the Synapse and start mautrix-whatsapp containers
    1. uncomment app_service_config_files and give the path of registration file:
app_service_config_files:
  - /data/whatsapp-registration.yaml
    1. restart Synapse server
    2. start mautrix-whatsapp container with following parameters:
docker run --network host -p 29318:29318 -v /volume1/docker/mautrix-whatsapp:/data:z dock.mau.dev/tulir/mautrix-whatsapp:latest

Note that you can also use the dedicated Docker Matrix_Network rather than host network but it requires using Matrix server’s internal Container IP address for appservice address and hostname in config.yaml

  1. to enable WhatsApp Web mode, connect to your Matrix account with element https://app.element.io/#/welcome from a browser (not from the main mobile you’re using):
    1. create a Direct Message with @whatsappbot:YOUR_MATRIX_DOMAIN and wait a few seconds the confirmation that the bot has joined the room

    1. help gives you all the commands you can use to interact with the bot

    1. in order to log on your actual WhatsApp account, type login
    2. the bot will show a QR Code

    1. from your WhatsApp app on mobile main screen, select the 3 dots (on top right) / WhatsApp Web / LINK A DEVICE and scan the Code
    2. Element will now synchronize all your WhatsApp chats
    3. Element will create Direct Messages for each WhatsApp direct chats and Rooms are created for Group chats – imported chats rooms are suffixed (WA)
    4. Accept the invite from the bot and you can start chatting with your WhatsApp contacts