A WhatsApp Web transport for the Extensible Messaging and Presence Protocol (XMPP), otherwise known as Jabber. (alpha!)
This is the spiritual successor of sms-irc, a similar project that works with IRC instead of XMPP.
What is this?
This is a multi-user transport for WhatsApp, using the [whatscl](https://git.theta.eu.org/eta/whatscl** library for Common Lisp. By scanning a QR code generated by the bridge with the WhatsApp app on your phone, you can send and receive messages and media with your Jabber ID.
Note: You currently need an XMPP server of your own to try this. It's only been tested with prosody 0.11 as of the time of writing - and there are some additional caveats: take a look at the requirements list.
- Sending private messages/DMs both ways
- Basic support for MUCs
- Magically populating your roster using XEP-0144: Roster Item Exchange
- Downloading/decrypting media from WhatsApp and uploading it to your XEP-0363 server
- Read receipts
- Status text
- Typing notifications / chat state
What doesn't yet?
- XEP-0313: Message Archive Management in MUCs (DMs should be done by your server)
- Support for users joining and leaving MUCs
- Support for the topic changing in MUCs
- Uploading media to WhatsApp (currently, it just comes through as a link)
- Probably other stuff
What you'll need
- An XMPP server (we recommend prosody, but it might also work with ejabberd; let us know!)
- You need to set up a new external component for the bridge (see prosody doc).
- In addition, you must configure an XEP-0363 (HTTP File Upload) component. (see prosody doc)
- WARNING: Prosody's
mod_http_uploaddoes not allow the bridge to use it, as of the time of writing (2020-05-28). You will need to replace
mod_http_upload.luain your community modules directory with
doc/mod_http_upload.luafrom this repository for it to work.
- WARNING: Prosody's
- An installation of Docker
- You can try and run the bridge without Docker. However, we really don't recommend it, especially if you aren't familiar with Common Lisp.
- Ask in the support MUC (link at the top of this file) if you want to do this.
- SQLite installed (specifically the
Step 1: configure your XMPP server
Make sure you've followed the links above to set up XEP-0363 and an external component for the bridge. With prosody, your config might look something like:
Component "upload.capulet.lit" "http_upload" http_upload_file_size_limit = 104857600 Component "whatsapp.capulet.lit" component_secret = "juliet"
Step 2: set up the database and storage for the bridge
I'm going to assume you want to store bridge data at the path
/wx. Replace this path
with wherever you actually want to put the data in the commands below.
Set up the database schema:
$ sqlite3 /wx/data.sqlite3 < ./schema.sql
Then, configure the bridge -- replacing the values below with the actual values:
$ sqlite3 /wx/data.sqlite3 SQLite version 3.31.1 2020-01-27 19:55:54 Enter ".help" for usage hints. sqlite> INSERT INTO configuration (rev, server, port, component_name, shared_secret, upload_component_name) VALUES (1, "capulet.lit", 5347, "whatsapp.capulet.lit", "juliet", "upload.capulet.lit"); sqlite> .quit
A few things to note here:
portis whatever port your XMPP server accepts incoming component connections on (not client-to-server or server-to-server connections!). For prosody, the default is 5347.
component_nameis whatever you specified in the prosody config for this component.
shared_secretis the same as the
upload_component_nameis the name of the XEP-0363 HTTP Upload component.
Step 3: run the bridge
You can build the Docker image yourself from the
Dockerfile in the repo, or you can just
use my hosted copy. (Don't download it a ton you guys, I pay for this stuff.)
You'll want to pass through the directory (
/wx, or whatever it is) where you created
the database as a Docker volume, so the container can access it. Then, supply the path
to the database as the first argument to the container.
The hosted image is called
eu.gcr.io/etainfra/whatsxmpp. Using the
you might run the bridge like so:
docker run \ --name whatsxmpp \ --restart always \ -v /wx:/data \ eu.gcr.io/etainfra/whatsxmpp /data/data.sqlite3
Consult the Docker reference for more details on this step, including how to run the image in the background and more!
If you see
Connection complete! \o/ in the logs, it's working!
Step 4: set up the WhatsApp Web part
You'll interact with the bridge by talking to
the last part of that JID will be different depending on your setup). Send this user
help to check that the bridge is working (you should get some help text).
To set it up, have your phone at the ready to scan the QR code (Menu -> WhatsApp Web).
register to the admin user, and scan the QR code you're given.
(Did it break at this part and give you a nasty error? Check your XEP-0363 HTTP Upload service is working correctly, and allows the bridge to use it as described above!**
You should then receive a crapton of presence subscription requests and MUC invites for everyone you are remotely related to on WhatsApp, and for all the WhatsApp groups you're in, and the bridge is done!
Tip: If your client supports XEP-0144: Roster Item Exchange (Gajim on desktop is good for this), send
getroster to the admin user
to pop up a window where you can insert all your WhatsApp contacts in one go!
Come join us in email@example.com if you have questions or issues using the bridge.