Contacts

After logging in to Agora 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.

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

Understand the tech

The Agora Chat SDK uses ChatContactManager 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.
• getAllContactsFromDB: Retrieves all contacts from the local database.
• addUserToBlockList: Adds the specified user to the block list.
• removeUserFromBlockList: Removes the specified user from the block list.
• getBlockListFromServer: Retrieves a list of blocked users from the server.

Prerequisites

Before proceeding, ensure that you meet the following requirements:

• Have a project that has implemented the basic real-time chat functionalities.
• Have a thorough understanding of the API call frequency limit, the maximum size of all the attributes of a specified user, and the maximum size of all user attribtues in an app. For details, see Known limitations.

Implementation

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

Add a contact

This section uses user A and user B as an example to describe the process of adding a peer user as a contact.

User A call addContact to add user B as a contact:

// Specify the user ID.
const userId = "foo";
// Set the reason for adding a contact.
const reason = "Request to add a friend.";
ChatClient.getInstance()
  .contactManager.addContact(userId, reason)
  .then(() => {
    console.log("request send success.");
  })
  .catch((reason) => {
    console.log("request send fail.", reason);
  });

When user B receives the contact invitation, accept or decline the invitation.

• To accept the invitation

  const userId = "bar";
  ChatClient.getInstance()
    .contactManager.acceptInvitation(userId)
    .then(() => {
      console.log("accept request success.");
    })
    .catch((reason) => {
      console.log("accept request fail.", reason);
    });

• To decline the invitation

  const userId = "bar";
  ChatClient.getInstance()
    .contactManager.declineInvitation(userId)
    .then(() => {
      console.log("decline request success.");
    })
    .catch((reason) => {
      console.log("decline request fail.", reason);
    });

User A uses ContactEventListener to listen for contact events.

• If user B accepts the invitation, onContactInvited is triggered.

  const contactEventListener = new (class implements ChatContactEventListener {
    that: any;
    constructor(parent: any) {
      this.that = parent;
    }
    onContactInvited(userId: string, reason?: string): void {
      console.log(`onContactInvited: ${userId}, ${reason}: `);
    }
  })(this);
  ChatClient.getInstance().contactManager.addContactListener(
    contactEventListener
  );

• If user B declines the invitation, onFriendRequestDeclined is triggered.

  const contactEventListener = new (class implements ChatContactEventListener {
    that: any;
    constructor(parent: any) {
      this.that = parent;
    }
    onFriendRequestDeclined(userId: string): void {
      console.log(`onFriendRequestDeclined: ${userId}: `);
    }
  })(this);
  ChatClient.getInstance().contactManager.addContactListener(
    contactEventListener
  );

Delete a contact

Call deleteContact to delete the specified contact. To prevent mis-operation, we recommend adding a double confirm process before deleting the contact.

// Specify the user to be deleted.
const userId = "tom";
// Whether to delete the conversation.
const keepConversation = true;
ChatClient.getInstance()
  .contactManager.deleteContact(userId, keepConversation)
  .then(() => {
    console.log("remove success.");
  })
  .catch((reason) => {
    console.log("remove fail.", reason);
  });

Add a user to the block list

Call addUserToBlockList to add the specified user to the block list. Once you add a user to the block list, you can no longer receive messages from this user.

// Specify the user ID to be added to the block list.
const userId = "tom";
// Call addUserToBlockList.
ChatClient.getInstance()
  .contactManager.addUserToBlockList(userId)
  .then(() => {
    console.log("add block list success.");
  })
  .catch((reason) => {
    console.log("add block list fail.", reason);
  });

Retrieve the block list

To get the block list from the local device, call getBlockListFromDB.

ChatClient.getInstance()
  .contactManager.getBlockListFromDB()
  .then((list) => {
    console.log("get block list success: ", list);
  })
  .catch((reason) => {
    console.log("get block list fail.", reason);
  });

You can also retrieve the block list from the server by calling getBlockListFromServer.

ChatClient.getInstance()
  .contactManager.getBlockListFromServer()
  .then((list) => {
    console.log("get block list success: ", list);
  })
  .catch((reason) => {
    console.log("get block list fail.", reason);
  });

Remove a user from the block list

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

const userId = "tom";
// Call removeUserFromBlockList
ChatClient.getInstance()
  .contactManager.removeUserFromBlockList(userId)
  .then((list) => {
    console.log("remove user to block list success: ", list);
  })
  .catch((reason) => {
    console.log("remove user to block list fail.", reason);
  });