QuickBlox Documentation

QuickBlox provides powerful Chat API and SDK to add real-time messaging and video calls to your web and mobile apps. Learn how to integrate QuickBlox across multiple platforms.

Contact List

Learn how to create, update, manage, and add users to your contact list.

The Contact List API is rather straightforward. A user A sends a request to become "friends" with a user B. The user B accepts the friend request. And now the user A and B appear in each other roster.
This feature is also useful to get online/offline statuses of the users from the user's Contact List.

Visit our Key Concepts page to get an overall understanding of the most important QuickBlox concepts.

Before you begin

  1. Register a QuickBlox account. This is a matter of a few minutes and you will be able to use this account to build your apps.
  2. Configure QuickBlox SDK for your app. Check out our Setup page for more details.
  3. Create a user session to be able to use QuickBlox functionality. See our Authentication page to learn how to do it.
  4. Connect to the Chat server. See our Connection page to learn how to do it.

Add listener

To use a contact list, you have to obtain it and set all needed listeners.

QBRosterListener rosterListener = new QBRosterListener() {
    @Override
    public void entriesDeleted(Collection<Integer> userIds) {
 
    }
 
    @Override
    public void entriesAdded(Collection<Integer> userIds) {
 
    }
 
    @Override
    public void entriesUpdated(Collection<Integer> userIds) {
 
    }
 
    @Override
    public void presenceChanged(QBPresence presence) {
 
    }
};

QBSubscriptionListener subscriptionListener = new QBSubscriptionListener() {
    @Override
    public void subscriptionRequested(int userId) {
    // Subscription was requested by user with ID = userId
    }
};

// You should do this after login (connect) to the Chat
QBRoster contactsRoster = QBChatService.getInstance().getRoster();

contactsRoster.setSubscriptionMode(QBRoster.SubscriptionMode.mutual);
contactsRoster.addSubscriptionListener(subscriptionListener);
contactsRoster.addRosterListener(rosterListener);
val rosterListener = object : QBRosterListener { 
    override fun entriesDeleted(collection: Collection<Int>?) {

    }

    override fun entriesAdded(collection: Collection<Int>?) {

    }

    override fun entriesUpdated(collection: Collection<Int>?) {

    }

    override fun presenceChanged(qbPresence: QBPresence?) {

    }
}

val subscriptionListener = QBSubscriptionListener { userId: Int -> {
    // Subscription was requested by user with ID = userId
    }
}

// You should do this after login (connect) to the Chat
val contactsRoster = QBChatService.getInstance().roster

contactsRoster.subscriptionMode = QBRoster.SubscriptionMode.mutual
contactsRoster.addSubscriptionListener(subscriptionListener)
contactsRoster.addRosterListener(rosterListener)

The following table lists all supported events of the QBRosterListener.

Event

Description

entriesDeleted()

A contact list item is removed from the contact list.

entriesAdded()

A new contact list item is added to the contact list.

entriesUpdated()

A contact list item is updated. For example, a user's name can be updated.

presenceChanged()

A user presence is changed.

Care should be taken when using the presence data delivered as part of this event. Specifically, when a user account is online with multiple devices, the UI should account for that. For example, say a user is online with their desktop computer and mobile phone. If the user logs out of the instant messaging client on their mobile phone, the user should not be shown in the contact list as offline since they're still available on another device.

🚧

You should call chatService.getRoster() only after successful connecting to Chat. To learn how to it, review this section.

QBRosterListener is a listener that is fired any time a contact list is changed or the presence of a user in the contact list is changed (e.g. user becomes online/offline).

QBSubscriptionListener is a listener that is called subscriptionRequested when the current user has been requested for adding to the Contact List from any user.

Access contact list

The following function gives you access to all contact list items.

Collection<QBRosterEntry> entries = contactsRoster.getEntries();
val entries = contactsRoster.entries

A QBRosterEntry describes a user entity in your contact list. To get the Presence of a user, use getPresence(userID) method. Then, you can get a user's status.

QBPresence presence = contactsRoster.getPresence(user.getId());

if (presence == null) {
    // no user in your contact list
    return;
}
if (presence.getType() == QBPresence.Type.online) {
    // user is online
} else {
    // user is offline
}
val presence = contactsRoster.getPresence(user.id)

if (presence == null) {
    // no user in your contact list
    return
}
if (presence.type == QBPresence.Type.online) {
    // user is online
} else {
    // user is offline
}

Add user to your contact list

To add a user to the contact list, use the following snippet.

try {
    contactsRoster.subscribe(user.getId());
} catch (SmackException.NotConnectedException e) {

}
try {
    contactsRoster.subscribe(user.id)
} catch (e: SmackException.NotConnectedException) {

}

After that, the User you have just subscribed to, receives a callback subscriptionRequested in QBSubscriptionListener. This is a request to be added to the contact list.

// QBSubscriptionListener

// ...

@Override
public void subscriptionRequested(int userId) {

}
// QBSubscriptionListener()

// ...

@Override
public void subscriptionRequested(int userId) {

}

📘

Maximum number of contacts is 300.

Confirm the contact request

To confirm the request, use contactsRoster.confirmSubscription() method.

try {
    contactsRoster.confirmSubscription(user.getId());
} catch (SmackException.NotConnectedException | SmackException.NotLoggedInException | SmackException.NoResponseException | XMPPException e) {

}
try {
    contactsRoster.confirmSubscription(user.id)
} catch (e: SmackException.NotConnectedException) {

} catch (e: SmackException.NotLoggedInException) {

} catch (e: SmackException.NoResponseException) {

} catch (e: XMPPException) {

}

Reject the contact request

To reject the request, use the contactsRoster.reject() method.

try {
    contactsRoster.reject(user.getId());
} catch (SmackException.NotConnectedException e) {

}
try {
    contactsRoster.reject(user.id)
} catch (e: SmackException.NotConnectedException) {

}

Remove user from the contact list

To remove a previously added user from the contact list, use the following method.

try {
    contactsRoster.unsubscribe(user.getId());
} catch (SmackException.NotConnectedException e) {

}
try {
    contactsRoster.unsubscribe(user.id)
} catch (e: SmackException.NotConnectedException) {

}

Contact list updates

The above-specified RosterListener listener will give you all updates regarding contact list changes and users' status updates.

Updated 5 months ago


What's Next

Privacy list

Contact List


Learn how to create, update, manage, and add users to your contact list.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.