Looking for the previous docs site? Visit the legacy docs homepage. (opens in a new tab)
Agora Docs

Contacts

Updated

Shows how to use the Agora Chat SDK to implement contact management.

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

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.

Understand the tech

The Chat SDK uses ChatContactManager to add, remove and manage contacts. The following 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 blocklist.
  • removeUserFromBlockList: Removes the specified user from the blocklist.
  • getBlockListFromServer: Retrieves a list of blocked users from the server.

Prerequisites

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.

Implementation

This section shows how to manage contacts with the methods provided by the 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 check 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 blocklist

Call addUserToBlockList to add the specified user to the blocklist.

You can add any other users to the blocklist, 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 blocklist. After adding users to the blocklist, you can still send messages to them, but will not receive messages from them as they cannot send messages or friend requests to you.

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

Retrieve the blocklist

To get the blocklist from the local device, call getBlockListFromDB.

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

You can also retrieve the blocklist from the server by calling getBlockListFromServer.

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

Remove a user from the blocklist

To remove the specified user from the blocklist, call removeUserFromBlockList.

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

Contact Us

+1 (408) 879-5885

2804 Mission College Blvd.Santa Clara, CA, USA 95054

AgoraCopyright © 2026 AgoraAll rights reserved