Profanity Illustration

User Guide

Managing Your Contacts

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 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 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