synapse-docker-bridges/config/mautrix-whatsapp/README.md

WhatsApp Bridge Setup Guide

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

Prerequisites

Before starting, ensure that:

• Synapse 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

1. Navigate to the WhatsApp configuration directory:

cd config/mautrix-whatsapp

2. Generate the initial configuration file:

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

3. 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://synapse:password@postgres/synapse?sslmode=disable

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

4. Generate the registration file:

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

5. Configure Synapse to use the WhatsApp bridge by editing config/synapse/homeserver.yaml:

app_service_config_files:
- "/etc/whatsapp/registration.yaml"

6. Start the bridge service:

docker compose up -d mautrix-whatsapp

7. Restart Synapse 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

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

Double Puppeting

Double puppeting makes messages you send from WhatsApp appear as coming from your Matrix account instead of a ghost user. To enable it:

1. You'll need the access token that was displayed when you created your Matrix user with the create-user.sh script.
2. Start a private chat with @whatsappbot:your.domain.com.
3. Send the command: login-matrix <access-token>. (Replace <access-token> with your saved access token from create-user.sh).
4. The bot should confirm successful double puppeting setup.

Note: If you've lost your access token, you can generate a new one using Element or another Matrix client in Settings > Help & About > Access Token.

Troubleshooting

1. Bridge Not Starting

   • Verify that both config.yaml and registration.yaml exist.
   • Check file permissions.
   • Review logs with docker compose logs mautrix-whatsapp.

2. 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.

3. 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.

4. 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.