WhatsApp bridge setup with Docker


  • Docker
  • A Matrix homeserver that supports application services (e.g. Synapse)


Docker images are hosted on dock.mau.dev

  1. 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.
  2. Pull the docker image with docker pull dock.mau.dev/mautrix/whatsapp:latest.
  3. 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/mautrix/whatsapp:latest
  4. Update the config to your liking. Don't forget to change the address and domain to match those of your server, and add yourself to the permissions section.
  5. Generate the appservice registration by running the container again, same command as above.
  6. Add the path to the registration file (registration.yaml by default) to your Synapse's homeserver.yaml under the app_service_config_files section.
  7. Restart Synapse to apply changes.
  8. Run the bridge:
    docker run --restart unless-stopped -p 29318:29318 -v `pwd`:/data:z dock.mau.dev/mautrix/whatsapp:latest
    N.B. If using postgres database hosted at localhost/ (outside the container), then use --network=host to avoid errors like dial tcp connect: connection refused


  1. Pull the new version (setup step 1)
  2. Start the new version (setup step 7)