Skip to content
WhatsApp<->IRC gateway bot
Python Shell
Find file
Latest commit a73706e Sep 8, 2014 @stenyak refs #24 Correctly detects ":" target user in messages.
Should stop dropping smileys and similar stuff.
Failed to load latest commit information.
yowsup.git @ 6b83dad Bump yowsup version Jan 28, 2014
.gitignore Version symlink to yowsup. Mar 19, 2013
.gitmodules Add yowsup as submodule. Mar 19, 2013 Update Aug 17, 2014
Yowsup Version symlink to yowsup. Mar 19, 2013
agpl-3.0.txt Added license file. Nov 14, 2012 refs #18 Private whatsapp messages were not directed at the phone num… Jul 10, 2014 Added catch_them_all wrapper to all threads and callbacks. Nov 19, 2012
config.json Update to whatsapp auth protocol v2 released in december 2012. Jan 3, 2013 Yowsup fork seems to be up again, git submodule restored. Jul 10, 2014 Improved logs for better readability. Feb 13, 2014 refs #24 Correctly detects ":" target user in messages. Sep 8, 2014 refs #24 Correctly detects ":" target user in messages. Sep 8, 2014 Migrated to new log class. Nov 14, 2012 Fixed a test. Nov 14, 2012 refs #19 Fix private whatsapp messaging API. Jul 10, 2014



Breakbot is a software that serves as gateway between several communication protocols.

It was started as a way to scratch one of the author's own itch, i.e. to break free from the walled garden that WhatsApp is, and to be able to use a proper computer with a proper screen and a proper keyboard (I hate long chats in tiny screens).

It currently supports:

  • WhatsApp group chats <-> IRC rooms gatewaying.
  • WhatsApp phone numbers <-> IRC nick conversion.
  • WhastApp image and video attachments.
  • Private messaging

Things it does not currently support:

  • DCC send, topic changes, etc.
  • Other protocols such as XMPP or ICQ.


Contact info is at the bottom of this document.


Breakbot is in early stages, lacks documentation everywhere, needs refactoring, may set fire to your computer, take your jobs... the usual drill. Just don't blame me for any problem it causes.

Getting started


You'll need a WhatsApp account (phone number + password) that Breakbot will use.

Note that WhatsApp does not allow simultaneous connections, so you may want to get a secondary phone number for your Breakbot (e.g.: buy a second SIM card, or get a free number at fonyou, etc). Otherwise the bot would log you out of your phone's WhatsApp client.

You can register a WhatsApp account for your number without an actual physical phone, by following step #4 in the list below.


Note: all phone numbers must be specified as international number without 00 or +. E.g: Spanish number 600600600 would become 34600600600


  1. Clone the Breakbot repo.
  2. Get the dependencies installed by running ./
  3. Add your bots to whatever WhatsApp group chats you want to bridge.
  4. [optional] Register the phone number against WhatsApp account using the last two options of python Yowsup/yowsup-cli -h.
  5. Initial setup: open config.json, go to config section, and customize all the fields.
    • wa_password is the base64-encoded password as returned by the --exists option of yowsup-cli
    • wa_phone is the phone number used by the bot to connect to WhatsApp. See Requisites above.
    • irc_* parameters are what you expect.
    • bot_owner_nick is the IRC nick of the bot owner (needed for private messaging).
  6. Make sure your bot nick and phone are also in the contact list.
  7. Run python so that it connects to WhatsApp
    • Watch the screen for strings matching Those are the WhastApp group chats. Write them down somewhere.
    • Control+C to stop Breakbot.
  8. Final setup: open config.json, go to contacts section, and:
    • Add the desired WhatsApp group chats you wrote down to that list, together with the IRC rooms you want them bridged to.
    • Add the phone numbers and what IRC nick they map to.


Just cross your fingers, run python and wait for your bot to appear at the specified IRC channels (should take about 5-10 seconds with a proper connection).

Once connected, everything you say on IRC should appear on WhastApp and vice versa.


You can notify me about problems and feature requests at the issue tracker

Feel free to hack the code and send me GitHub pull requests, or traditional patches too; I'll be more than happy to merge them.

The author Bruno Gonzalez can be reached at and /dev/null for personal praise and insults, respectively.

Something went wrong with that request. Please try again.