Contents
Overview
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 companies 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 buddy@service.net
With optional nickname:
/roster add buddy@service.net MyBuddy
You can add a contact to the roster and send a subscription request at the same time, by using the /sub
command:
/sub request buddy@service.net
To remove a contact from the roster:
/roster remove buddy@service.net
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
command:
/roster nick bob@company.org Bobster
To clear a users nickname:
/roster clearnick bob@company.org
Managing groups
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 /group
command.
To list all the current groups:
/group
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
command:
/sub request newcontact@server.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:
/sub request
Approving a request
You can approve subscription requests from contacts using the /sub
command:
/sub allow newcontact@server.com
The contact parameter is optional if you are already in a chat window with the user, the approval will be sent to that user:
/sub allow
Deny or delete a request
You can deny subscription requests from contacts using the /sub
command:
/sub deny newcontact@server.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
The /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:
/sub sent
To list requests that you have received, but not yet approved or denied, use the following command:
/sub received