7 Authentication
Tulir Asokan edited this page 2019-11-24 21:37:28 +02:00

Logging in

  1. Start a chat with the bridge bot.
    • You can for instance create a new room and type /invite @whatsappbot:matrix.example.com to invite the bot (assuming you did not change the bot username in config and your Matrix homeserver is running at matrix.example.com).
    • The bot should say "This room has been registered as your bridge management/status room." if you started the chat correctly.
    • If the bot doesn't accept the invite and there's nothing in the bridge logs, the most likely cause is that the config or registration is misconfigured, e.g. homeserver not restarted correctly or mismatching as_token or hs_token
  2. Send login to the bot
  3. Log in by scanning the QR code. If the code expires before you scan it, the bridge will send an error to notify you.
    1. Open WhatsApp on your phone.
    2. Tap Menu or Settings and select WhatsApp Web.
    3. Point your phone at the image sent by the bot to capture the code.
  4. Finally, the bot should inform you of a successful login and the bridge should start creating portal rooms for your recent WhatsApp groups and private chats.

Please note that the bridge uses the web API, so your phone must be connected to the internet for the bridge to work. The WhatsApp app doesn't need to be running all the time, but it needs to be allowed to wake up when receiving messages (should work by default). The web API is used instead of the main client API to avoid bans (WhatsApp will ban unofficial clients).

Replacing WhatsApp account's Matrix puppet with Matrix account

N.B. Currently only users on the same homeserver as the bridge can log in with their Matrix account.

When you are logged in with your WhatsApp account, you can replace the Matrix puppet of your WhatsApp account with your Matrix account. When you do so, messages that you send from the main WhatsApp app will be sent from your Matrix account.

Also, until matrix-org/synapse#2954 is fixed, it is the only way to enable bridging of ephemeral events, such as presence, typing notifications and read receipts.

  1. Get an access token for your account, e.g. from the "Help & About" section in Riot web settings.
  2. Log in by sending login-matrix <access token> to the bridge bot.
  3. After logging in, the default Matrix puppet of your WhatsApp account should leave rooms, and your account should join all rooms the puppet was in.

Logging out

Simply run the logout management command.