148 lines
6.7 KiB
Markdown
148 lines
6.7 KiB
Markdown
|
# whatsxmpp
|
||
|
|
|
||
|
|
[](https://www.gnu.org/licenses/agpl-3.0.en.html)
|
||
|
|
[](xmpp:whatsxmpp@conf.theta.eu.org?join)
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
|
||
|
|
A WhatsApp Web transport for the [Extensible Messaging and Presence Protocol (XMPP)](https://xmpp.org/), otherwise known as Jabber. (alpha!)
|
||
|
|
|
||
|
|
*This is the spiritual successor of [sms-irc](https://git.theta.eu.org/eta/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](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:
|
||
|
|
|
||
|
|
```
|
||
|
|
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:
|
||
|
|
|
||
|
|
- 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 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](https://docs.docker.com/engine/reference/run/) 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 `admin@whatsapp.capulet.lit` (well,
|
||
|
|
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).
|
||
|
|
Then, send `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](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!
|
||
|
|
|
||
|
|
## Support
|
||
|
|
|
||
|
|
[](xmpp:whatsxmpp@conf.theta.eu.org?join)
|
||
|
|
|
||
|
|
Come join us in [whatsxmpp@conf.theta.eu.org](xmpp:whatsxmpp@conf.theta.eu.org?join) if you
|
||
|
|
have questions or issues using the bridge.
|