# 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:

```sh
cd config/mautrix-whatsapp
```

2. Generate the initial configuration file:

```sh
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
```yaml
homeserver:
    address: http://monolith:8008  # Internal Docker network address
    domain: your.domain.com        # Replace with your actual domain
```

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

#### Bridge Settings
```yaml
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:

```yaml
# 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:

```sh
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`:

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

6. Start the bridge service:

```sh
docker compose up -d mautrix-whatsapp
```

7. Restart Synapse to load the new bridge configuration:

```sh
docker compose restart monolith
```

## Verifying the Setup

Check if the bridge is running:

```sh
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](../mautrix-telegram/README.md).

For more detailed information about bridge features and configuration options, visit the [mautrix-whatsapp documentation](https://docs.mau.fi/bridges/general/docker-setup.html?bridge=whatsapp).