155 lines
4.5 KiB
Markdown
155 lines
4.5 KiB
Markdown
# 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
|
|
|
|
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://dendrite:password@postgres/dendrite?sslmode=disable
|
|
|
|
# Modified (note 'whatsapp' database name):
|
|
postgres://dendrite: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 Dendrite to use the WhatsApp bridge by editing `config/dendrite/dendrite.yaml`:
|
|
|
|
```yaml
|
|
app_service_api:
|
|
config_files:
|
|
- "/etc/whatsapp/registration.yaml"
|
|
```
|
|
|
|
6. Start the bridge service:
|
|
|
|
```sh
|
|
docker compose up -d mautrix-whatsapp
|
|
```
|
|
|
|
7. Restart Dendrite 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).
|