WhatsApp Bridge Setup Guide

This guide will help you set up the WhatsApp bridge for your Dendrite Matrix server.

Prerequisites

Before starting, ensure that:

Dendrite is properly configured and running.
The whatsapp database was created during the initial setup.
You have your domain name ready.
You have access to a WhatsApp account with an active phone number.
Your phone has the WhatsApp app installed and working.

Setup Steps

Navigate to the WhatsApp configuration directory:

cd config/mautrix-whatsapp

Generate the initial configuration file:

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

Edit the generated config.yaml file. You may need administrative privileges (sudo) to edit this file.

Required Configuration Changes

Make the following modifications to your config.yaml:

Homeserver Settings

homeserver:
    address: http://monolith:8008  # Internal Docker network address
    domain: your.domain.com        # Replace with your actual domain

Appservice Settings

appservice:
    address: http://whatsapp:29318  # Internal bridge address
    hostname: 0.0.0.0               # Listen on all interfaces

Bridge Settings

bridge:
    permissions:
        "*": relay
        "your.domain.com": user           # Replace with your domain
        "@yourusername:your.domain.com": admin  # Replace with your Matrix ID

Database Connection

Update the database URI to use the WhatsApp-specific database:

# Original:
# postgres://dendrite:password@postgres/dendrite?sslmode=disable

# Modified (note 'whatsapp' database name):
postgres://dendrite:password@postgres/whatsapp?sslmode=disable

Generate the registration file:

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

Configure Dendrite to use the WhatsApp bridge by editing config/dendrite/dendrite.yaml:

app_service_api:
    config_files:
        - "/etc/whatsapp/registration.yaml"

Start the bridge service:

docker compose up -d mautrix-whatsapp

Restart Dendrite to load the new bridge configuration:

docker compose restart monolith

Verifying the Setup

Check if the bridge is running:

docker compose logs mautrix-whatsapp

You should see messages indicating the bridge has started successfully. If the configuration files aren't present, the service will remain stopped - this is normal and prevents unnecessary restarts.

Using the Bridge

Start a chat with @whatsappbot:your.domain.com in your Matrix client.
Send the command !wa login to start the login process.
You will receive a QR code in the chat.
Open WhatsApp on your phone:
- Go to Menu or Settings.
- Select "WhatsApp Web".
- Scan the QR code displayed in Matrix.
Wait for the confirmation message.

Troubleshooting

Bridge Not Starting
- Verify that both config.yaml and registration.yaml exist.
- Check file permissions.
- Review logs with docker compose logs mautrix-whatsapp.
QR Code Issues
- Make sure your phone can properly scan the QR code.
- Request a new QR code with !wa login.
- Ensure your phone has a stable internet connection.
Connection Problems
- Check if WhatsApp is properly connected on your phone.
- Verify bridge service is running.
- Check bridge logs for errors.
- Try logging out and back in.
Message Delivery Issues
- Verify WhatsApp connection status.
- Check bridge permissions.
- Ensure proper room creation.

Next Steps

Proceed to set up the Telegram Bridge.

For more detailed information about bridge features and configuration options, visit the mautrix-whatsapp documentation.