Jabber User Guide

Last Updated: 2004-08-17

Copyright © 1999 - 2006 by the Jabber Software Foundation


This document shows how to use Jabber clients to perform common instant messaging tasks.

Table of Contents

1.0 Introduction
2.0 How Jabber Works
3.0 Choosing a Jabber Client
4.0 Choosing a Jabber Server
5.0 Registering An Account
6.0 Testing it Out
7.0 Groupchat
8.0 Enabling People to Find You
9.0 Finding People
9.1 Exodus
9.2 Gabber
10.0 The Subscription Handshake
11.0 Managing Your Roster
12.0 Finding Gateways
13.0 Using Gateways
14.0 Getting Assistance
15.0 Reporting Bugs
16.0 Conclusion
Appendix A: Common IM Acronyms

1.0 Introduction

Welcome to the wonderful world of Jabber!

Jabber is an open-source instant messaging platform that uses open, XML-based protocols to create the standard functionality people expect of an IM system: one-to-one chat, multi-user chat, the ability to subscribe to someone else's presence, and so on. (See the Jabber Overview for details.)

Jabber is not a multi-protocol IM client, so if all you want to do is chat with your friends on AIM, ICQ, MSN, and Yahoo, you may be better off using something like Trillian or Gaim (which also support Jabber). Although many Jabber servers run gateways to the legacy IM services, Jabber is not primarily focused on such interoperability, because it is outside our control -- only AOL, Microsoft, and Yahoo can decide when they will work towards an open standard for instant messaging.

Instead, the Jabber community is focused on building a truly open alternative to legacy IM services. So Jabber might be for you if:

If that sounds like you, then we invite you to get started with Jabber by working your way through this user guide. But we warn you: Jabber can be addictive! :)

2.0 How Jabber Works

Jabber is lovable, but it's not always easy. To forestall confusion in getting started with Jabber, it's important to know a little bit about how it works.

There is a tradition in Jabber documentation of using examples from Shakespeare, so let's think about two Shakespeare characters and how they exchange messages -- perhaps Juliet up on the balcony, and Romeo down in the Capulets' orchard. Now Juliet doesn't send a message directly ("peer to peer") to her Romeo, at least not in the Jabber world. Juliet has an account on a Jabber server, and her Jabber address (we call it a Jabber ID or "JID") looks a lot like an email address. Since Juliet is a Capulet, she registers the username "juliet" with the Jabber server running at capulet.com, so her JID is juliet@capulet.com. Similarly, Romeo has an account on his family's server and his JID is romeo@montague.net.

Once Juliet has logged into the capulet.com server, she can send messages to her sweetie. To be precise, here is what actually happens when Juliet fires up the Exodus client on her Windows laptop out on the balcony:

  1. Juliet sends a message addressed to romeo@montague.net

  2. The message is handled by the Jabber server at capulet.com

  3. The capulet.com server opens a connection to montague.net

  4. Assuming that the family elders have not disabled server-to-server communications between capulet.com and montague.net, Juliet's message is routed to the Jabber server at montague.net

  5. The server at montague.net sees that the message is addressed to an actual user named "romeo" and delivers it to the Jabber client running on Romeo's Linux laptop out in the Capulets' orchard

  6. The message pops up in Gabber, and Romeo swoons

There are a lot of pieces here: clients running on different operating systems, multiple servers, a communication channel between the servers, and two star-crossed lovers. Jabber handles everything but the last part, and you have a great deal of choice in which parts you use and how. So the first step is to make some of those decisions. Let's start by Choosing a Jabber Client....

3.0 Choosing a Jabber Client

Which Jabber client is best for you depends on which operating system you run, what your needs are, and to some extent what IM systems you've used before. Some clients are more stable than others, some offer more features, some are more similar to AIM or ICQ or MSN, and so on. The Jabber clients covered in this user guide are Exodus for Windows (http://exodus.jabberstudio.org/) and Gabber for Linux (http://gabber.sourceforge.net/), although there are many other Jabber clients to choose from (refer to http://www.jabber.org/software/clients.php for a complete list) and the functionality is usually similar in other clients. (However, be aware that some Jabber clients do not implement the complete Jabber protocol, which means they may be missing some features.)

Once you've chosen a Jabber client, follow the program's installation procedures and start the program so you can Choose a Jabber Server....


Jabber communications occur over port 5222. If you are behind a firewall, you may not be able to use a downloadable Jabber client.

4.0 Choosing a Jabber Server

In order to use Jabber, you must register an account with a Jabber server -- it's similar to setting up an account with an ISP or configuring your email client to connect to your organization's email server. As with Jabber clients, which server is best for you depends on your needs (for instance, you may be using your organization's own Jabber server). The public server that the Jabber Software Foundation runs here at jabber.org is a favorite choice, but there are plenty of other public Jabber servers to choose from (refer to http://www.jabber.org/user/publicservers.php for a directory of public Jabber servers). Best of all, the service is free.

Once you've chosen a Jabber server, the next step is Registering An Account....

5.0 Registering An Account

If you are using a public Jabber such as jabber.org, there is (in general) no formal process for requesting a username. All you do is try to log in with your desired Jabber ID and password. If it doesn't work (e.g., because your Jabber ID is taken), try again. (If you are using a private Jabber server, for example a server running on a company's intranet, you may need to contact the server administrator in order to register an account.)

Here's how to register an account with a public server. When you first open Exodus or Gabber, you'll see a start screen such as that shown below:

Start Screen in Exodus

The start screen (login screen) in Exodus.

Start Screen in Gabber

The start screen (login screen) in Gabber.

Fill in the information for Server (e.g., capulet.com), Username (e.g., juliet), and Password (e.g., R0m30). The "Resource" field helps Jabber know which instance of your Jabber account to send messages to (e.g., if you have Jabber clients installed on multiple computers), so you can put information about your location (e.g., balcony) or the name of the program (e.g., Exodus).

Click "OK" or "Login" as appropriate and your Jabber client will attempt to log in to the server you specified.

Important Note About Usernames!

Usernames are case-insensitive, so "StPeter" is the same as "stpeter". Also, Jabber usernames are limited to 1023 characters (not that you'll ever need a username that long, but just in case...). In addition, certain characters are not allowed in your username:

If your preferred username is taken at a domain, you may be asked to try a different username:

Username taken warning in Exodus

Being prompted for a different username in Exodus.

Username taken warning in Gabber

Being prompted for a different username in Gabber.

If your desired username is still available, your Jabber client will ask you if you want to create an account:

Account creation in Exodus

Being prompted to create an account in Exodus.

Account creation in Gabber

Being prompted to create an account in Gabber.

Click "Yes" and your account will be created.

Congratulations: you are now connected to the Jabber network! There's only one way to know if your account is working: Test it Out....

6.0 Testing it Out

The public Jabber server at jabber.org runs an "echo" service that enables you to send a message and receive the same message in reply. This is quite basic, but it enables you to test whether your account is working. To perform this test, send a new message by selecting Exodus > Send Message in Exodus or Services > New Blank Message in Gabber. You'll see an input box or a message window:

Sending a message in Exodus

Sending a message in Exodus (screen 1 of 2).

Sending a message in Exodus

Sending a message in Exodus (screen 2 of 2).

Sending a message in Gabber

Sending a message in Gabber.

For the JID, enter jabber.org/echo, then type a message and click "Send" or hit the Return key. (The subject is optional.) You will almost immediately receive an echo of your your message. (Note: if you send a message to "jabber.org" without the "echo" resource", it will be delivered to the jabber.org server admins.)

The echo service is pretty boring, though. For a more interactive test, we'll be Joining a Chatroom....

7.0 Groupchat

One of Jabber's many cool features is the ability to engage in a discussion with many people at once (a.k.a. "groupchat"). And you're not limited to the chatrooms on the server you registered with -- you can join chatrooms on servers all over the Jabber network. This page describes how to join a chatroom that often has a fair number of new users in it.

Select Exodus > Join Conference (Exodus) or Services > Join Group Chat (Gabber) to bring up the window for joining a group (Exodus | Gabber).

Joining a chatroom in Exodus

Joining a chatroom in Exodus.

Joining a chatroom in Gabber

Joining a chatroom in Gabber.

Fill in the appropriate information for the room you want to join (type jabber), the conferencing service (type conference.jabber.org), and your desired nickname (e.g., juliet). You will see a groupchat window that may look familiar to you if you have ever used IRC or some other groupchat system:

Participating in a chatroom in Exodus

Participating in a chatroom in Exodus.

Participating in a chatroom in Gabber

Participating in a chatroom in Gabber.

Type your messages in the input box at the bottom and hit Return to send them to the group. It's as simple as that!

8.0 Enabling People to Find You

Note: While the method described below will work, you may find GTalk Profile easier to use!

Sending a message to a bot or chatting with random strangers in a chatroom is all fine, well, and good, but the main attraction of instant messaging is the ability to talk with your friends and family in real time. To do chat with someone, you need to know their Jabber ID (or convince them to try Jabber). Unfortunately, you're not necessarily going to know the Jabber ID of the person you're trying to reach. So the question naturally arises: how do you find people in Jabber?

Certainly you can tell all your friends about Jabber or advertise your Jabber ID on your website or in your email signature. However, Jabber also has its own directory containing basic information about some of the many people who use Jabber. This directory is called the Jabber User Directory, and is known affectionately as JUD. Actually there can be any number of such directories, but the main JUD is located at the jabber.org server. While you are not automatically added to this directory when you register with a Jabber server (that would violate our respect for individual privacy), you can choose to add yourself to this directory if you would like other people to be able to find you.

To add yourself to the JUD, select Tools > Edit My vCard (Exodus) or Gabber > My Information (Gabber) and click the Personal tab to add your information:

Adding yourself to JUD in Exodus

Adding yourself to JUD in Exodus.

Adding yourself to JUD in Gabber

Adding yourself to JUD in Gabber.

When you're done, click "OK" to send your information to the JUD.

OK, now you're in the user directory. But we still haven't talked about how to find people in the JUD....

9.0 Finding People

Note: While the method described below will work, you may find GTalk Profile easier to use (however, right now it works only if your email address is the same as your Jabber ID -- they are working to make it more generic). Also check out the Qunu service to find experts on various topics.

The process for finding people by searching the JUD is a bit different in Exodus vs. Gabber, so we'll cover them separately here.

9.1 Exodus

In Exodus, select Tools > Contacts > Search for a Contact (or just Cntrl-F). You will see the following screen:

Searching JUD in Exodus

Searching JUD in Exodus.

Type in the criteria you'd like to search on (first name, last name, Jabber ID, etc.) and click "OK". JUD will return a list of users who match your criteria:

Viewing JUD results in Exodus

Viewing JUD results in Exodus.

Now you can easily add the desired user to your contact list (in Jabber we call it your "roster") by clicking the user's entry and then clicking the "Add Contacts" button. As we discuss in detail in the next section, that will send a subscription request to the person you selected.

9.2 Gabber

In Gabber, searching for people is a byproduct of adding someone to your contact list (in Jabber we call it your "roster"). Gabber has a "wizard" that walks you through this process, so the first step is to select Services > Add Contact. Click the "Next" button on the first screen, then click "Jabber User Directory" on the second screen and click "Next" again. You will be presented with a search form:

Searching JUD in Gabber

Searching JUD in Gabber.

Type in the criteria you'd like to search on (first name, last name, Jabber ID, etc.) and click "OK". JUD will return a list of users who match your criteria:

Viewing JUD results in Gabber

Viewing JUD results in Gabber.

Now you can easily add the desired user to your roster by clicking the user's entry and then clicking the "Next" button. Gabber will present you with a few more screens in the wizard (all of which are fairly straightforward). When you click the final "Next" button, Gabber will send a subscription request to the person you selected (we discuss this in detail in the next section).

10.0 The Subscription Handshake

One of the key concepts of instant messaging is presence -- the ability to know when someone is online and available for chatting. Unlike some of the legacy IM services, Jabber respects individual privacy. So in order for you and a friend to see each other's presence, you need to make a mutual agreement to do so, rather like a handshake in real life. Here's what happens:

  1. You send a subscription request to your friend. If you know the exact JID, you can just do Tools > Contacts > Add Contact in Exodus or Services > Add Contact in Gabber:

    Adding a contact in Exodus

    Adding a contact in Exodus.

    Adding a contact in Gabber

    Adding a contact in Gabber.

  2. Your friend receives a subscription request from you, and can accept or reject it:

    Receiving a subscription request in Exodus

    Receiving a subscription request in Exodus.

    Receiving a subscription request in Gabber

    Receiving a subscription request in Gabber.

  3. If your friend accepts the subscription request, their Jabber client will send a subscription request to you.

  4. If you accept your friend's request, the "handshake" will be complete and now each of you will know when the other person is online.

11.0 Managing Your Roster

In Jabber, the list of people you've subscribed to is called your roster (in other IM services this is called a contact list or buddy list). If you're just starting out in Jabber, you might only have a few people in your roster (perhaps a friend or co-worker who convinced you to give it a try). At the other end of the spectrum are friendly Jabber fanatics who have hundreds of people in their rosters!

Once you have more than a few people in your roster, you'll want to manage how your roster appears. One way to do this in Jabber is by setting up groups. For instance, you might want to have roster groups for friends, co-workers, and so on. You have total control over the groups in your roster, and each contact can be in one or more of your roster groups.

Each Jabber client handles groups in a slightly different way. For instance, often you can drag and drop a contact from one group to another. To create a new group you may need to select a specific contact in your roster and change which group they are in. In Exodus you do this by right-clicking the contact in your roster and selecting the Properties option, then the Groups tab, whereas in Gabber you do it by right-clicking the contact in your roster and selecting the Edit Groups option:

Creating a group in Exodus

Creating a group in Exodus.

Creating a group in Gabber

Creating a group in Gabber.

12.0 Finding Gateways

One of the things people like about Jabber is that you can communicate with users of legacy IM services like AIM, MSN, ICQ, and Yahoo. Unlike all-in-one IM clients like Trillian, what makes this possible in Jabber is a piece of software called a gateway (or "transport"), which runs in conjunction with a Jabber server such as jabber.org. Unfortunately not every Jabber server runs every gateway (in fact the jabber.org server doesn't run any!), so you may need to hunt around for working gateways.

To find working gateways, it may seem like you would have to keep registering accounts with new Jabber servers all the time in search of the one server that runs every gateway you need. Thankfully, the people who designed Jabber's architecture were pretty smart, so you don't have to do this. Instead, you can keep your "home" Jabber account and "browse" to other servers to see what services they offer. To do this, select Select Tools > Jabber Browser (Exodus) or Services > Browse Agents/IM Systems (Gabber):

Browsing to another server in Exodus

Browsing to another server in Exodus.

Browsing to another server in Gabber

Browsing to another server in Gabber.

In the example shown above, the user typed in jabber.at as the server and clicked the Browse button. The result? We can see that this server is running the ICQ, MSN, and Yahoo gateways. Now you can register with the gateways of your choice and chat with friends on those other networks.

Now, don't all use the poor jabber.at server -- we don't want to overload any one Jabber server! Select one of the Jabber servers listed at http://www.jabber.org/user/publicservers.php. (And if you really want to help out, run a server of your own or convince your ISP to do so. Visit http://www.jabber.org/admin/ for more information.)

13.0 Using Gateways

Assuming you have found a working gateway, there are several steps you need to complete in order to chat with friends on legacy IM services:

  1. First, you need to have an account on the other network. (Why? See the note at the bottom of this section.)

  2. Select Tools > Jabber Browser (Exodus) or Services > Browse Agents/IM Systems (Gabber). You will see window that lists the available gateways and other server-side agents:

    Viewing available gateways in Exodus

    Viewing available gateways in Exodus.

    Viewing available gateways in Gabber

    Viewing available gateways in Gabber.

  3. Select the appropriate gateway and click the "Register with this object" link (Exodus) or click the Register button (Gabber). You will see a registration wizard (Exodus) or window (Gabber):

    Registering with a gateway in Exodus

    Registering with a gateway in Exodus (screen 1 of 2).

    Registering with a gateway in Exodus

    Registering with a gateway in Exodus (screen 2 of 2).

    Registering with a gateway in Gabber

    Registering with a gateway in Gabber.

  4. Provide the information requested and complete the form or wizard.

  5. The appropriate gateway is now added to your roster.

  6. Now, to add a user of that IM network, proceed just as you normally would in adding a contact but choose "MSN Transport" or whatever as the user type (if your Jabber client is not this smart, see "Another Note" below).

Now you can chat with that user just as you would any other Jabber user. It's as easy as that!


Why do you need an account on the non-Jabber network? Because there are no common protocols for communication between IM networks. It's as if you needed to use different email clients to talk with people who use Compuserve or Hotmail or AOL for email. The only way Jabber can talk with other networks is to act as a "proxy" for you on other IM networks (important: this means the Jabber gateway needs to store your username and password so that it can log in as you; if you're not comfortable with that, don't register with the gateways -- or run your own server!). Crazy, huh? BTW, because the gateway essentially logs in like a normal IM client, you cannot run Jabber and a legacy IM client at the same time once you add the relevant gateway to your roster. If you would like to go back to using that IM service directly and still run Jabber, you need to delete the relevant gateway from your roster.

Another Note

Not all Jabber clients are smart enough to handle gateways. You may need to use a more advanced Jabber client to register with the gateway, after which you can use it from your other Jabber client. To add contacts who use IM services that have addresses like user@host (MSN is one of these), you may need to manually construct the Jabber ID for this person. Jabber gateways do this by changing the "@" in the foreign address into "%", then adding the address of the gateway. So let's say that you have a friend whose MSN address is JoeCool@hotmail.com and that you have registered with the MSN gateway at msn.jabbernet.dk; you would then enter your friend's Jabber ID as JoeCool%hotmail.com@msn.jabbernet.dk (yes, this is long but it is necessary). However, this transformation is not necessary for AIM, ICQ, and Yahoo addresses, so you probably have to worry about it only to contact your MSN friends.

14.0 Getting Assistance

Need help with your Jabber client? Try the "jabber" conference room mentioned in the groupchat section of this user guide. There is also a dedicated mailing list for Jabber users, so feel free to sign up for that at http://mail.jabber.org/mailman/listinfo/juser.

15.0 Reporting Bugs

Almost everyone who writes Jabber software does it for fun in their spare time. However, that doesn't mean they don't have a professional attitude about the software they write. So if you think you've found a bug, report it at the website of the Jabber client you're using. Please report bugs so we can keep improving Jabber!

16.0 Conclusion

Finally, thank you for trying Jabber! We hope this Jabber User Guide has helped you get started with Jabber. If you have questions that are not answered here, send an email to the JUser mailing list.

Happy Jabbering!

Appendix A. Common IM Acronyms

First-time instant messaging users are often confused by the plethora of acronyms used in the IM world. Here is a short list of acronyms you might see when chatting with other Jabber users:

afaikas far as I know
afaictas far as I can tell
afkaway from keyboard
atmat the moment
bbiabbe back in a bit
bbiafbe back in a few (minutes)
bblbe back later
bbsbe back soon
bfoblinding flash of the obvious
brbbe right back
bsodblue screen of death
btwby the way
ciaoItalian for goodbye
ctrncan't talk right now
cul8rsee you later
cyasee ya
dhtbdon't have the bandwidth
f2fface to face
fubarf***ed up beyond all recognition
fwiwfor what it's worth
fyifor your information
gmtagreat minds think alike
iamin a meeting
ianalI am not a lawyer
ihmbI hate my boss
iircif I recall correctly
imhoin my humble opinion
imoin my opinion
iowin other words
irlin real life
gmtagreat minds think alike
gtggot to go
jidjabber identifier
j/kjust kidding
lollaugh out loud
n/mnever mind
n/pno problem
oAoover and out!
omgoh my god
oobout of band
otohon the other hand
owwoops, wrong window!
otpon the phone
pitapain in the ass
povpoint of view
rotflrolling on the floor laughing
rsnreal soon now
rtfmread the friendly manual
slapsounds like a plan
tiathanks in advance
tlathree-letter arconym
ttfnta ta for now
ttyltalk to you later
wbwelcome back
wfmworks for me
wtfwhat the f***?!
wtgway to go!
ymmvyour mileage may vary