Using the WhatsApp bridge

Overview

This guide describes how to bridge your Element and WhatsApp accounts. This allows you to chat with WhatsApp contacts and groups natively within Element.

Before you can carry out the steps in this guide, ensure you have the following:

• WhatsApp - You will need a phone with WhatsApp installed and a registered account.
• Element - You will need a Matrix account to log into Element, and a WhatsApp bridge set up on your Matrix homeserver.

Note: When setting up the Whatsapp bridge you will need to scan a QR code generated in Element from your phone. To make this process as easy as possible, we recommend using Element Web for the initial setup, once set up you can then login to any platform with your Element account and use the bridge which you have set up. However, it is possible with two mobile phones if you can quickly take a photo of the QR code with one phone and then scan it with the original phone.

Setting up

Sign into Element Web using your Element username and password.

(If asked to verify your login, see docs on verifying a new login.

Once signed in, start a new direct message with the WhatsApp bridge bot. (It will not work if you create a room with the bridge bot, it needs to be a direct message)

The username of the bot will be @whatsappbot:your.server (for example @whatsappbot:matrix.org)

Ensure that your.server is the homeserver where the bridge is hosted. This may be different to the homeserver hosting your own account.

Click on the suggested WhatsApp bridge bot, and click Go to start the direct message.

You will be taken into a new room with the WhatsApp bridge bot. The bot automatically joins the room.

Remaining in the room, send the login command by sending login into the room.

Tip: You can also send the command **help** to get a list of all available commands.

The bot will generate a QR code to scan from WhatsApp on your phone.

Leaving Element open, open WhatsApp on your phone for the next step

In WhatsApp, tap the three dots (⋮) in the top right corner of the app.

From the drop-down menu tap Linked devices.

Tap LINK A DEVICE.

Tap OK to begin scanning the QR code.

Scan the QR code generated by the WhatsApp bot in Element.

The WhatsApp bridge now shows as a linked device in DEVICE STATUS.

If this doesn't work the first time, it is likely that the QR code has expired, you will need to repeat the steps again and scan the QR code before it expires.

Back in Element, the bridge bot will confirm that you have logged in to WhatsApp.

The bridge then creates rooms to allow you to chat with WhatsApp contacts and groups. By default the bridge automatically creates rooms for people or groups you have interacted with in the last week. Others are created as new messages arrive. See below for how to use bridged rooms.

Note: WhatsApp requires your phone to connect to your WhatsApp account every 14 days to keep the bridge active, otherwise you will need to QR code scan again. So ensure you open the WhatsApp app every 14 days to ensure you are not disconnected.

Using direct messages

The bridge will automatically invite you to new rooms for your recent contacts.

WhatsApp contacts automatically have (WA) added to their display name.

To start, click on a room invite and join the room.You will be taken into the new room for your WhatsApp contact.

You can now begin chatting with your WhatsApp contact in the same way as any other Element user.

(Note that the bridge does not support voice or video calling.)

Starting new chats (or resuming older ones that were not automatically set up) can be done with the pm command, followed by the number for the other person in international format. For example to invite whatsapp number +4412345678 you would send the command pm +4412345678 into the WhatsApp bridge bot room.

Tip: Using the list contacts command retrieves your existing WhatsApp contacts, including their numbers. You can then click on the contact and click message to start chatting.

Once the pm command is sent the bridge will invite you to a new room for the WhatsApp chat.

Using rooms

You will automatically be invited to some rooms for WhatsApp group chats that have been automatically created by the bridge. If this has not happened you can manually open an existing group chat.

To open an existing WhatsApp group in Element, you can use the list groups command (send the message list groups into the WhatsApp bridge bot room) to get a list of all WhatsApp groups. Each will be shown with its ID

Use the open command, followed by the ID of the group. For example you can see the Office part ghroup chat has the room ID 447818943525-1636277287, so you would send the command open 447818943525-1636277287.

The bridge will then create a room for the group and invite you.

Disconnecting from WhatsApp

To disconnect WhatsApp from Element enter the logout command, by sending logout into the WhatsApp brtidge bot room. This will remove the linked device from WhatsApp.

As a further option, the connection to WhatsApp can be forcibly disconnected by using the delete-session command. This removes the connection at the Element side but does not perform a graceful logout from WhatsApp.

Once logged out, the delete-all-portals command can be used to clean up rooms previously created by the bridge.