There are two parts to managing contacts, the roster and presence subscriptions.
The roster is a list of all of your contacts.
To receive updates about a contacts presence, i.e. to see when they are online and their current status, you must be subscribed to that contact.
For a contact to receive updates about your presence, you must have approved a subscription request from that contact.
Some servers may have already set up your roster and subscriptions for you, for example, many companys integrate with LDAP, and automatically subscribe all users to all other users.
The following sections describe roster and subscription management in more detail.
Viewing your roster
To view all contacts in your roster, use the
/roster command. The output gives you the following information:
|JID and nickname||The contacts Jabber ID, and nickname if you have provided one.|
|Subscription||The current subscription status, and whether you have received or sent a request that has not yet been approved or declined.|
|Groups||The list of groups to which the contact belongs, see groups below.|
The subscription status may be one of:
|none||You are not subscribed to the contact, and the contact is not subscribed to you.|
|to||You are subscribed to the contact, but they are not subscribed to you.|
|from||You are not subscribed to the contact, but they are subscribed to you.|
|both||You are subscribed to the contact, and they are subscribed to you.|
Adding and removing contacts
To add a contact to the roster, use the
/roster command supplying the Jabber ID and optional nickname:
/roster add email@example.com
With optional nickname:
/roster add firstname.lastname@example.org MyBuddy
You can add a contact to the roster and send a subscription request at the same time, by using the
/sub request email@example.com
To remove a contact from the roster:
/roster remove firstname.lastname@example.org
Removing a contact from your roster also removes your subscription to their presence, and their subscription to yours.
Giving contacts a nickname
Some servers automatically give your contacts nicknames (when integrating with LDAP for example), which are more human readable than the Jabber ID.
Profanity uses nicknames by default in its user interface, and for most commands relating to contacts.
If the server allows it, you may change, add or remove the nickname for a given contact using the
/roster nick email@example.com Bobster
To clear a users nickname:
/roster clearnick firstname.lastname@example.org
The roster allows contacts to be added to named groups. Profanity makes use of groups using the
/who command to filter the contacts shown.
Roster groups are managed with the
To list all the current groups:
To show the contacts in a particular group:
/group show friends
To add a contact to a group:
/group add friends Buddy
Note that there is no command to add a group, adding a contact to a group that doesn't yet exist will create the group.
To remove a contact from a group:
/group remove friends Buddy
Subscribing to a contact
To request presence information for a contact use the
/sub request email@example.com
The user will be informed that you wish to know of their presence, and will need to approve the request.
The contact parameter is optional if you are already in a chat window with the user, the request will be sent to that user:
Approving a request
You can approve subscription requests from contacts using the
/sub allow firstname.lastname@example.org
The contact parameter is optional if you are already in a chat window with the user, the approval will be sent to that user:
Deny or delete a request
You can deny subscription requests from contacts using the
/sub deny email@example.com
The contact parameter is optional if you are already in a chat window with the user, the denial will be sent to that user:
/sub deny command can also be used to remove a contacts subscription to your presence if you have previously approved it.
List pending requests
To list requests that you have sent that are awaiting approval from the contact, use the following command:
To list requests that you have received, but not yet approved or denied, use the following command: