Contacts

After logging in to Chat, users can start adding contacts and chatting with each other. They can also manage these contacts, for example, by adding, retrieving and removing contacts. They can also add the specified user to the block list to stop receiving messages from that user.

Agora Chat, by default, allows two users to send chat messages to each other as strangers. This means that users can chat without adding each other as a contact. If you only allow chat between contacts, you can contact support@agora.io to enable the friend relationship check switch. After this function is enabled, the SDK will check whether the two users trying to chat are on the contact list of each other. If no, the SDK will report error code 221.

This page shows how to use the Chat SDK to implement contact management.

The Chat SDK uses ContactManager to add, remove and manage contacts. Followings are the core methods:

• addContact: Adds a contact.
• acceptInvitation: Accepts the contact invitation.
• declineInvitation: Declines the contact invitation.
• deleteContact: Deletes a contact.
• getAllContactsFromServer: Retrieves a list of contacts from the server.
• addUserToBlackList: Adds the specified user to the block list.
• removeUserFromBlackList: Removes the specified user from the block list.
• getBlackListFromServer: Retrieves a list of blocked users from the server.

Before proceeding, ensure that you meet the following requirements:

• You have integrated the Chat SDK, initialized the SDK and implemented the functionality of registering accounts and login. For details, see Chat SDK quickstart.
• You understand the API call frequency limits as described in Limitations.

This section shows how to manage contacts with the methods provided by the Chat SDK.

Use this section to understand how to send a contact invitation, listen for contact events, and accept or decline the contact invitation.

Call addContact to add the specified user as a contact:

_2

//The parameters are the username of the contact to be added and the reason for adding

_2

ChatClient.getInstance().contactManager().addContact(toAddUsername, reason);

Use ContactListener to add the following callback events. When a user receives a contact invitation, you can accept or decline the invitation.

_22

ChatClient.getInstance().contactManager().setContactListener(new ContactListener() {

_22

_22

//The contact request is approved

_22

@Override

_22

public void onFriendRequestAccepted(String username) { }

_22

_22

//contact request is rejected

_22

@Override

_22

public void onFriendRequestDeclined(String username) { }

_22

_22

//Received contact invitation

_22

@Override

_22

public void onContactInvited(String username, String reason) { }

_22

_22

//Call back this method when deleted

_22

@Override

_22

public void onContactDeleted(String username) { }

_22

_22

//Call back this method when a contact is added

_22

@Override

_22

public void onContactAdded(String username) { }

_22

});

After receiving onContactInvited, call acceptInvitation or declineInvitation to accept or decline the invitation.

_5

// Accept the contact invitation

_5

ChatClient.getInstance().contactManager().acceptInvitation(username);

_5

_5

// Decline the contact invitation

_5

ChatClient.getInstance().contactManager().declineInvitation(username);

Call deleteContact to delete the specified contact. The deleted user receives the onContactDeleted callback.

_1

ChatClient.getInstance().contactManager().deleteContact(username);

To get the contact list, you can call getAllContactsFromServer to retrieve contacts from the server. After that, you can also call getContactsFromLocal to retrieve contacts from the local database.

_5

// Retrieves a list of contacts from the server

_5

List<String> usernames = ChatClient.getInstance().contactManager().getAllContactsFromServer();

_5

_5

// Retrieves a list of contacts from the local database

_5

List<String> usernames = ChatClient.getInstance().contactManager().getContactsFromLocal

You can add a specified user to your block list. Once you do that, you can still send chat messages to that user, but you cannot receive messages from them.

Users can add any other chat user to their block list, regardless of whether this other user is a contact or not. A contact added to the block list remains in the contact list.

Call addUserToBlackList to add the specified user to the block list.

You can add any other users to the block list, regardless of whether they are on the contact list or not. Contacts are still displayed on the contact list even if they are added to the block list. After adding users to the block list, you can still send messages to them, but will not receive messages from them as they cannot send messages or friend requests to you.

_2

// The effect of true and false is the same. I can send messages to users on the blacklist, but I cannot receive them when they send me messages.

_2

ChatClient.getInstance().contactManager().addUserToBlackList(username,true);

To remove the specified user from the block list, call removeUserFromBlackList.

_1

ChatClient.getInstance().contactManager().removeUserFromBlackList(username);

To get the block list, call getBlackListFromServer to retrieve a list of blocked users from the server.

_1

ChatClient.getInstance().contactManager().getBlackListFromServer();

After retrieving the block list from the server, you can also call getBlackListUserNames to retrieve the block list from the local database.

_1

ChatClient.getInstance().contactManager().getBlackListUsernames();