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
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):
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
- If a user changes their @mention name while you’re connected, Bitlbee won’t
pick up the change.
- There are some corner cases with getting invited to rooms, and when new rooms
are added, where the auto channel name mapping doesn’t seem to always work
- At least once I actually got a segfault while running this branch. This
happened immediately after trying to join a newly created room that had I had
just been invited to, where I had joined it under both the unmangled name and
the mangled name. I didn’t have core dumps enabled and wasn’t later able to
reproduce the issue, so I’m not sure exactly what the bug here is.
- Sometimes I would get disconnected from the HipChat server and BitlBee would
be unable to reconnect. I’m not sure if this is actually a BitlBee issue or
an issue with HipChat’s XMPP gateway.
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 127.0.0.1
This will daemonize BitlBee and have it bind to 127.0.0.1:6667. 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
account add hipchat firstname.lastname@example.org 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.
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
#bar. To do that, you’d use the following command in the BitlBee
chat add hipchat email@example.com #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:
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