WhatsApp Bridge #

Based on mautrix-whatsapp, the most feature-complete Matrix ↔ WhatsApp bridge. Uses the same multi-device pairing that WhatsApp Web and WhatsApp Desktop use, so no phone number re-registration is needed.

WhatsApp uses Signal-protocol E2EE natively. The bridge participates in the encryption on the WhatsApp side AND your Matrix room can independently be E2EE — messages are encrypted at every hop.

Prerequisites #

Meldry plan: Business
A working WhatsApp account on your phone — the bridge uses your phone as the "primary device", exactly like linking WhatsApp Web
Your phone online when linking (messages can still sync later when the phone is offline, but the initial pair requires it to be reachable)

Enable the bridge #

Dashboard → Server → Bridges → WhatsApp → Enable.
Wait ~10 seconds for the container. The bot appears at @whatsappbot:<your-name>.meldry.com.

Link your WhatsApp account #

In your Matrix client, DM @whatsappbot:<your-name>.meldry.com.
Send login.
The bot replies with a QR code image. Open it at full size in your Matrix client.
On your phone, open WhatsApp → Settings → Linked devices → Link a device. Point the camera at the QR code.
WhatsApp registers your Meldry bridge as a linked device. The bot replies Successfully logged in as +14155550001.
The bridge backfills your recent chats as Matrix rooms within a minute.

What gets bridged #

1:1 chats → Matrix DM rooms, with your contact's display name and avatar puppeted.
Groups → Matrix rooms under a WhatsApp space.
Media — photos, videos, voice notes, documents, stickers. All downloaded, re-encrypted and re-uploaded to Matrix.
Reactions, replies, edits, deletes → bidirectional.
Read receipts → bidirectional, respecting your WhatsApp privacy settings.
Status updates → NOT bridged (WhatsApp's Stories feature is not part of the multi-device API).
Communities and broadcast lists → partial support.
Voice and video calls → NOT bridged (WhatsApp's Signal-protocol calls can't be proxied).

Commands reference #

Command	What it does
`login`	Start QR-code pairing
`logout`	Unlink from WhatsApp (also unlinks on the phone's linked-devices list)
`status`	Show link health
`list-contacts`	List your WhatsApp contacts
`pm <+countrynumber>`	Start a DM with a WhatsApp number
`sync`	Force a resync of all chats
`help`	Full command list

The linked-device limit #

WhatsApp caps you at 4 linked devices per phone number (5 including the phone itself). If you're already using WhatsApp Web on a computer, WhatsApp Desktop and WhatsApp for iPad, the bridge link is your fourth slot. Check Settings → Linked devices on the phone to see what's using slots.

Phone-offline behavior #

On the legacy (pre-multi-device) WhatsApp bridge, your phone had to stay online. The current multi-device bridge works even if your phone is off — but:

For the first ~14 days of being linked, WhatsApp may require your phone to ping in every few days or the link is revoked.
After the bridge has "proven" itself, it can run standalone.

If your phone stays off for too long and the link is revoked, just re-run login and scan a new QR code.

Troubleshooting #

QR code expires — WhatsApp regenerates it every ~30 seconds. Run login again if you miss the window.

"WhatsApp says this device is already linked" — Open Settings → Linked devices on your phone and unlink any stale Meldry entry, then re-run login.

Messages suddenly stop syncing — the link was revoked. Usually a phone software update or a prolonged phone-offline period. Re-run login.

Contact names missing — WhatsApp's multi-device API only gives you contacts that the phone has already synced. Open the chat on your phone once, then run sync in the bridge DM.

Media doesn't download — Meldry's bridge downloads media into your workspace's media store. Check your storage quota (Dashboard → Server → Resources).

Privacy considerations #

Your WhatsApp messages traverse Meldry infrastructure while being bridged. They're E2EE on both ends but momentarily decrypted at the bridge process to re-encrypt for Matrix.
Your phone number is stored in the bridge database. Deleting the bridge deletes the credential.
Meldry does not log or retain message content beyond what's needed for the Matrix room state.