Bitlbee Quickstart Guide (Online Edition) & Notes


BitlBee allows you to chat on Instant Messaging protocols within your IRC client, it is an open source project released under GnuGPL v2.

The main page for Bitlbee is at, which is where you'll need to go if you want more information about what it is, where to download, how to try it out without installing anything, and lots of other wonderful things. For documentation on installing, connecting and other things check out Bitlbee's external documentation page.


Step One: Registering
Step Two: Add and Connect to your IM Account(s)
Step Three: Managing Contact Lists: Rename
Step Four: Managing Contact Lists: Add and Remove
Step Five: Chatting



The center of BitlBee is the control channel, &bitlbee. Two users will always be there, you (where "you" is the nickname you are using) and the system user, root. This quickstart guide navigates you through the first steps you may want to take when you begin using Bitlbee.

Step One: Registering

You need register so that all your IM settings (passwords, contacts, etc) can be saved on the BitlBee server. It's important that you pick a good password so no one else can access your account. Register with this password using the register command: register <password> (without the brackets!).

Be sure to remember your password. The next time you connect to the BitlBee server you will need to identify <password> so that you will be recognised and logged in to all the IM services automatically.

Step Two: Add and Connect To your IM Account(s).

To add an account to the account list you will need to use the account add command: account add <protocol> <username> <password> [<server>].

For instance, suppose you have an ICQ account with UIN 72696705 with password QuickStart, you would:

<you> account add oscar 72696705 QuickStart
<root> Account successfully added

Other available IM protocols are jabber, msn, and yahoo. Oscar is the protocol used by ICQ and AOL. For oscar, you need to specify the IM-server as a fourth argument (for msn and yahoo there is no fourth argument). For AOL Instant Messenger, the server name is For ICQ, the server name is

When you are finished adding your account(s) use the account on command to enable all your accounts

Step Three: Managing Contact Lists: Rename

For most protocols (currently MSN, Jabber, Yahoo and AOL) BitlBee can download the contact list automatically from the IM server and all the on-line users should appear in the control channel when you log in.

BitlBee will convert names into irc-friendly form (for instance: will be given the nickname tux). If you have more than one person who would have the same name by this logic (for instance: and the second one to log on will be tux_. The same is true if you have a tux log on to AOL and a tux log on from Yahoo.

It would be easy to get these two mixed up, so BitlBee has a rename command to change the nickname into something more suitable: rename <oldnick> <newnick>

<you> rename tux_ bitlbeetux
* tux_ is now known as bitlbeetux
<root> Nick successfully changed

Step Four: Managing Contact Lists: Add and Remove

Now you might want to add some contacts, to do this we will use the add command. It needs two arguments: a connection ID (which can be a number (try account list), protocol name or (part of) the screenname) and the user's handle. It is used in the following way: add <connection> <handle>

<you> add 0
* r2d2 has joined &bitlbee

In this case r2d2 is online, since he/she joins the channel immediately. If the user is not online you will not see them join until they log on.

Lets say you accidentally added rather than, or maybe you just want to remove a user from your list because you never talk to them. To remove a name you will want to use the remove command: remove <nick>

Step Five: Chatting

First of all, a person must be on your contact list for you to chat with them (unless it's a group chat, help groupchats for more). If someone not on your contact list sends you a message, simply add them to the proper account with the add command. Once they are on your list and online, you can chat with them in &bitlbee:

<you> tux: hey, how's the weather down there?
<tux> you: a bit chilly!

If you'd rather chat with them in a separate window use the /msg or /query command, just like you would for a private message in IRC. If you want to have messages automatically come up in private messages rather than in the &bitlbee channel, use the set private command: set private true (set private false to change back).

You now know the basics.


These are just some notes I threw together for my own reference. Remove < > brackets when using these commands, when [ ] brackets are used it means the field is optional or conditional.

In order to see the commands that bitlbee offers, type: help commands in the bitlbee control channel. You can type help <subject> for more detailed help on each subject. You will find many very useful settings by just typing set.

  • account add <protocol> <username> <password> [<server>] -- for specific information about connecting to each type of IM server try help account add <protocol>.
  • account del <account id> -- get the account id using list
  • account list -- lists all your accounts, including the account id which is required for such things as deleting accounts and managing users.
  • info <nick> -- requests info such as user info and away message (does not work on all protocols)
  • identify <password> -- identify yourself with bitlbee server
  • add <account id> <handle> [<nick>] -- adds user to your contact list
  • set <charset> -- change the charset, iso8859-1 is default
  • set strip_html true -- strips HTML from clients that use it