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](https://prosody.im/) as of the time of writing - and there are some
additional caveats: take a look at the requirements list.
## What works?
- Sending private messages/DMs both ways
- *Basic* support for MUCs
- Magically populating your roster using [XEP-0144: Roster Item Exchange](https://xmpp.org/extensions/xep-0144.html)
- Downloading/decrypting media from WhatsApp and uploading it to your XEP-0363 server
- Avatars
- Read receipts
- Status text
- Typing notifications / chat state
## What doesn't yet?
- [XEP-0313: Message Archive Management](https://xmpp.org/extensions/xep-0313.html) 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](https://prosody.im/), 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](https://prosody.im/doc/components)).
- In addition, you **must** configure an [XEP-0363 (HTTP File Upload)](https://xmpp.org/extensions/xep-0363.html) component. ([see prosody doc](https://modules.prosody.im/mod_http_upload.html))
- **WARNING:** Prosody's `mod_http_upload` does not allow the bridge to use it, as of the time of writing (2020-05-28). You will need to replace `mod_http_upload.lua` in your community modules directory with `doc/mod_http_upload.lua` from this repository for it to work.
- An installation of [Docker](https://www.docker.com/)
- 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](https://www.sqlite.org/) installed (specifically the `sqlite3` command).
## Instructions
### 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:
- The `port` is 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.
- The `component_name` is whatever you specified in the prosody config for this component.
- The `shared_secret` is the same as the `component_secret`.
- The `upload_component_name` is 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 `docker` CLI,
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](https://xmpp.org/extensions/xep-0144.html) (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!
