BitlBee & HipChat

Update (2016-06-09): Quite a bit of this has changed in recent Bitlbee releases; please check this Bitlbee wiki page for the most up to date instructions of using HipChat with Bitlbee.

The chat system we use at work is HipChat. HipChat offers a web client (HTML and Javascript) as well as native clients for Windows, OS X, and Linux. It also offers an XMPP gateway, so if you don’t want to use the native client you can use any other XMPP chat client. The XMPP gateway is a little hacky because HipChat has extended the XMPP protocol with proprietary attributes to add custom features, e.g. HipChat has both the concept of a display name (i.e. the user’s full real name) as will as an @mention name that is used to alert people in chats. HipChat does not have a native IRC gateway.

I was really unhappy with the native Linux HipChat client for a number of reasons. I found it to be really slow and it used a ton of memory. It also hasn’t gotten the same amount of attention as the other native clients, and lags behind in a number of areas. Besides that, I’ve been using IRC for years and I’ve already built up a nice workflow with weechat (and previously with irssi) that I wanted to keep using.

If you want to use weechat, irssi, or some other IRC client to connect to HipChat, it turns out there’s a way—BitlBee provides an XMPP/IRC gateway. The way it works is BitlBee acts to you as an IRC server implementing the IRC protocol. On the backend it will translate between IRC and XMPP (or one of many other chat protocols like AIM, ICQ, Twitter, etc.).

About three years ago when I first tried using BitlBee with HipChat, it was really rough around the edges. It worked, but barely. There were a lot of problems with how it displayed user names and the workflow for adding and joining channel. Thankfully in the last few years this has gotten a lot better. This article will explain how to get set up with BitlBee and HipChat. Once you get everything working, you’ll get a neat IRC setup like this (assuming you’re using a console based client):

how it looks

Apologies for the impossibly small text, but you probably get the idea.

How To Use Bitlbee With HipChat

First I would recommend taking a look at the official docs here. This will give you an overview of the state of the world, and below I will provide some more specific advice as to the workflow I use.

If you’re feeling adventurous, in the upstream git repo there is a branch called feat/hip-cat that gives you almost native support for HipChat. If you use this branch, when you connect to the server you’ll see users show up with their IRC nick set to their @mention name. BitlBee will apply a mangling heuristic to room names to make a best guess as to what to name them (by lowercasing the room and removing spaces and special characters). What this means is if there’s a HipChat room with a name like “Engineering” you’ll probably be able to join it with an IRC command like /join #engineering, which is not true if you’re in the master branch. I ran on this hip-cat for about six months (until just now), and while it mostly works it is rough around the edges. I found problems in the following areas:

Additionally, you’ll find that the master branch gets a lot more commits made to it than the hip-cat branch. Due to these bugs, and the fact that I wanted to follow along with all of the latest stuff in master, I have switched to the master branch and it’s what I recommend.

Setting It Up

First install BitlBee. I would recommend getting it from git and building it yourself, but that’s obviously optional and if you want you can use a version packaged by your favorite distro. If you compile BitlBee from source, make sure that you have an appropriate /var/lib directory to store your profile. I had to manually create /var/lib/bitlbee and set it up with the correct permissions even though I configured BitlBee to use an alternate prefix (i.e. it seems not to respect a command like ./configure --prefix=$HOME/opt in this regard, and you’ll find that the ./configure script is not a real autoconf script).

You can start the server with a command like:

bitlbee -D -p 6667 -i

This will daemonize BitlBee and have it bind to If this works successfully, fire up your IRC client, connect to the IP and port you set up, and you should see a greeting banner from BitlBee.

Once you’ve done this, the following sequence will set up a HipChat account for you:

account add hipchat YOUR_HIPCHAT_PASSWORD
account hipchat on

Note that the BitlBee password does not have to be the same as your HipChat password, and in fact it’s a good idea to make them different. If you get an error in the register command above about not being able to write a file (as I initially did), make sure that you have a /var/lib/bitlbee directory on your system and that it’s writeable by the BitlBee process.

In the future when you connect to BitlBee you’ll be able to re-authenticate by using:


This will log you in and restore all of the channels that you’ve set up.

Managing Channels

Now that you’re logged in and you’ve created an account, it’s time to add some channels. Go to to get a channel list and the XMPP names. Let’s say that a channel is named 9999_foo and you want it to be mapped locally to the IRC channel whose name will be #bar. To do that, you’d use the following command in the BitlBee control window:

chat add hipchat #bar

After this you should be able to /join #bar and join the channel.

In the future, you may want to delete channels you’ve created, change their configuration, set up auto-joining, etc. This is a little bit cumbersome. What you need to do here is to know the internal BitlBee channel id that was given to the channel. You can see that with:

channel list

This will print the list of channels and their numbers.

To delete a channel:

channel CHANNEL_ID del

To set a channel to auto-join:

channel CHANNEL_ID set auto_join true

Chatting With Users

Users will show up as their @mention name. If you need to know a user’s real name, you can use the standard /whois command in IRC to get that information. I do not know how to do the opposite, that is search for a user’s @mention name (i.e. IRC nick) based on their real name.

Once you know a person’s name you can /msg nick in the usual way to chat with users.