whatsxmpp/README.md

# whatsxmpp

[![XMPP chatroom: whatsxmpp@conf.theta.eu.org](https://inverse.chat/badge.svg?room=whatsxmpp@conf.theta.eu.org)](xmpp:whatsxmpp@conf.theta.eu.org?join)
![Maintenance](https://img.shields.io/maintenance/yes/2021.svg)

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. Setup instructions assume [prosody](https://prosody.im); the bridge
also works on [ejabberd](https://www.ejabberd.im/), but is not officially supported (though swing by the support MUC and we might
be able to provide some pointers, who knows).

## What works?

- Sending private messages/DMs both ways
- 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
- [XEP-0313: Message Archive Management](https://xmpp.org/extensions/xep-0313.html) in MUCs *only when enabled in configuration*
- Fetching your entire message history from WhatsApp and making it available via MAM *only when enabled in configuration*
- Users joining and leaving MUCs, and the topic changing (partial, requires XMPP-side rejoin)
- Uploading images to WhatsApp natively

## What doesn't yet?

- Uploading non-image 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))
- 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:

**IMPORTANT**: The bridge MUST be allowed to upload things to the XEP-0363 server. For prosody's `mod_http_upload`, you should configure the
[`http_upload_access`](https://modules.prosody.im/mod_http_upload.html#access) option, as shown below. For ejabberd, you'll need to do something
with ACLs that I don't quite understand.

```
Component "upload.capulet.lit" "http_upload"
        http_upload_file_size_limit = 104857600
        http_upload_access = {"whatsapp.capulet.lit"}

Component "whatsapp.capulet.lit"
        component_secret = "juliet"
```

**WARNING**: Unless you want to run a public bridge (not recommended at this time), limit
access to the external component to only people on your server. (On prosody, add
`modules_disabled = { "s2s" }` to the component configuration.)

### Step 2: set up the database and storage for the bridge

Prepare your `docker-compose.yml` like this:

```

  whatsxmpp:
    build: ./whatsxmpp
    depends_on:
      - ejabberd
    links:
      - "ejabberd:ejabberd"
    volumes:
      - ./data/whatsxmpp:/data
    environment:
      - SERVER=ejabberd              # Server-Address (Name,IP,etc)
      - COMPONENT_NAME=wx.eris.cc    
      - SECRET=whatsappsucks
      - UPLOAD_NAME=upload.eris.cc   # Name of the upload-component
      - PORT=5234		     # Port on the Jabber server to connect to
      - MAM=yes			     # Any value will be accepted as true; disable by commenting out
      - HISTORY=yes		     # Any value will be accepted as true; disable by commenting out
      - DATABASE_PATH=/data

```
On failure while setting up ( e.g. wrong ip, secret, etc. ) you have to delete the created database in your volume. Check the logs for this

### Step 3: 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 chatroom: whatsxmpp@conf.theta.eu.org](https://inverse.chat/badge.svg?room=whatsxmpp@conf.theta.eu.org)](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.

## License

MIT