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 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 the Contact module to add, remove and manage contacts. Core methods include the following:

• addContact: Adds a contact.
• acceptContactInvite: Accepts the contact invitation.
• declineContactInvite: Declines the contact invitation.
• deleteContact: Deletes a contact.
• getContacts: Retrieves a list of contacts.
• addEventHandler: Adds the event handler.
• addUsersToBlocklist: Adds the specified user to the block list.
• removeUserFromBlocklist: Removes the specified user from the block list.
• getBlocklist: 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.

Manage the contact list

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

Send a contact invitation

Call addContact to add the specified user as a contact:

const message = "Hello!";
chatClient.addContact("username", message);

Listen for contact events

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

/**
 * msg indicates the result of triggering the callback
 */
chatClient.addEventHandler("handlerId", {
  // Occurs when the contact invitation is received
  onContactInvited: function (msg) {},
  // Occurs when the contact is deleted
  onContactDeleted: function (msg) {},
  // Occurs when a contact is added
  onContactAdded: function (msg) {},
  // Occurs when the contact invitation is declined
  onContactRefuse: function (msg) {},
  // Occurs when the contact invitation is approved
  onContactAgreed: function (msg) {},
});

Accept or decline the contact invitation

After receiving onContactInvited, call acceptContactInvite or declineContactInvite to accept or decline the invitation.

/**
 * Accepts the contact invitation
 */
chatClient.acceptContactInvite("username");

/**
 * Declines the contact invitation
 */
chatClient.declineContactInvite("username");

Delete a contact

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

chatClient.deleteContact("username");

Retrieve the contact list

To get the contact list, you can call getContacts.

chatClient.getContacts().then((res) => {
  console.log(res); // res.data > ['user1', 'user2']
});

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

Add a user to the block list

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

chatClient.addUsersToBlocklist({
  name: ["user1", "user2"],
});

Remove a user from the block list

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

chatClient.removeUserFromBlocklist({
  name: ["user1", "user2"],
});

Retrieve the block list from the server

To get the block list, call getBlocklist.

chatClient.getBlocklist();