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):
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:
- 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 correctly.
- 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 you:
account add hipchat you@yourcompany.com YOUR_HIPCHAT_PASSWORD
account hipchat on
register BITLBEE_PASSWORD
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:
identify BITLBEE_PASSWORD
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
YOURCOMPANY.hipchat.com/account/xmpp
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 9999_foo@conf.hipchat.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:
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.