Random Notes

Use WhatsApp via Your IRC Client with BitlBee

NOTE 2016-09-21: It seems whatsapp-purple has been abandoned by its maintainer. So the things in this guide may stop working over time, and your mileage may vary. This guide is left here for posterity.

Perceptive readers may know that I use a Jolla as my phone. This places quite a few restrictions on what programs can be used on it. For WhatsApp I used to use a native application called Mitäkuuluu by coderus. Unfortunately at some point the program was discontinued, the official Android® version did not run well on the phone and the whole thing was a hassle. So I searched for an alternative way of using WhatsApp, since it has some people I would have trouble contacting otherwise. Since my IRC client is always running (on my server) and is something I check often, I looked into what BitlBee had to offer. I got a setup working and decided to document it for others.


Note that while this is not directly mentioned in WhatsApp’s Terms of Services (reverse engineering the system is forbidden, though), it is unsupported and it is possible you will get banned as a result of doing this. WhatsApp has been banning users of 3rd party clients lately, so only do this if you don’t mind losing access to your account (in some cases they will lift the ban if you reconnect with the official client). In addition, the protocol is evolving, so this setup may break at any moment in the future.


For those that don’t know, BitlBee is a gateway between IRC and various other protocols. It acts as an IRC server that you use with your preferred IRC client. It models the remote protocols as IRC channels or private queries, making their usage look like you were using IRC normally. Personally I’ve been using it for ages for Facebook chat, Google chat and MSN Messenger (back when it was still alive).

It turns out that BitlBee itself does not contain any support for WhatsApp, but there is a way to add it. BitlBee can be compiled with libpurple support, enabling it to support protocols that libpurple implements. When you have libpurple support, you can use a libpurple WhatsApp client like whatsapp-purple. Proper instructions follow.



Ingredients you will need during the process (as I use Arch Linux I have also listed the AUR packages I use):


To register, use yowsup-cli to get a password. First, create a text file yowsup.conf with only the following line:


Obviously replace the number with your own number. Notice that it starts with the international country code (358 is for Finland) without the + in front. After the country code the leading 0, if any, should be omitted. This same rule applies for phone numbers also later on when using WhatsApp with BitlBee.

Now run the following command to request a registration code, which will be sent to your phone:

yowsup-cli registration -c '/path/to/yowsup.conf' -C 358 -r sms

Again, replace 358 with your actual country code.

You should receive an SMS with the WhatsApp registration code. Use it to run the next command:

yowsup-cli registration -c '/path/to/yowsup.conf' -C 358 -R <registration-code>

You should get back a bunch of output, where the password is the important detail. It will be used in BitlBee to connect.

Connecting with BitlBee

Install and set up bitlbee-libpurple and whatsapp-purple. When whatsapp-purple is set up correctly, the command help purple in the BitlBee command channel should list it as one of the protocol options. To add your WhatsApp account, use the command

acc add whatsapp 358451234567 <password>

substituting with your phone number and the password given by yowsup-cli.

The Mysterious Resource

If you list your account’s settings with account whatsapp set, you will see a value called “resource”. As far as I know, this is the value reported by the client to the server, telling what type of client it is. It seems to change from time to time, as the protocol and the libraries evolve. Earlier, it was required to claim that the client was an S40 client to get around encryption limitations. You can check the whatsapp-purple issue tracker for the latest proper value.

At the time of writing, a good value seems to be Android-2.31.151-443. To use it, run the following:

account whatsapp set resource Android-2.31.151-443


To add contacts, use the following:

add whatsapp 358451234567 fancypants
add whatsapp 358455555555 buddy
add whatsapp 358400101010 mother

Notice that they all follow the same number format as previously used. Don’t forget to save after adding contacts!

When you have your contacts set up, just open a query with them and talk. Here’s what it looks like in my client (WeeChat):

Discussing problems with the setup. 😛 See the Caveats section for details!

Group chats also work, but with some caveats. See the next section for details.


There are some problems with the setup, as is expected when reverse engineering a closed source system. Some of them are minor annoyances, some could be blockers depending on how much you love tinkering. Your mileage may vary.

  1. The setup is fragile. It has worked for me for a few months, but I’ve needed to pull the latest changes for whatsapp-purple and recompile a couple of times. I suggest always running the latest BitlBee and whatsapp-purple to keep it running smoothly, especially if you are suddenly unable to connect.
  2. You may need to change the resource as described above. The correct value can only be found by searching through the issue tracker.
  3. After restarting BitlBee or disconnecting and reconnecting the WhatsApp account, you cannot talk in group chats until someone else has spoken. If you join the channel before that, it will be empty. The first time someone speaks, everyone else will join in a huge stampede. I’m not aware of a fix for this at the time of writing.
  4. Images are received as a long string of HTML tags and URLs. Clicking on one of the URLs will open the image in the browser. Sometimes images crash BitlBee entirely.
  5. You may be banned by WhatsApp.