# Contacts (/en/realtime-media/im/build/build-core-messaging/contacts/flutter)

> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).

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](mailto\: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](mailto\: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](../../get-started-sdk).
* You understand the API call frequency limits as described in [Limitations](../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:

```dart
// The user ID that you want to add as a contact
String userId = "foo";
// Reasons for adding the user as a contact
String reason = "Request to add a friend.";
try{
  await ChatClient.getInstance.contactManager.addContact(userId, reason);
} on ChatError catch (e) {
}
```

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

* To accept the invitation

  ```dart
  // The user ID that sends the contact invitation
  String userId = "bar";
  try{
    await ChatClient.getInstance.contactManager.acceptInvitation(userId);
  } on ChatError catch (e) {
  }
  ```

* To decline the invitation

  ```dart
  // The user ID that sends the contact invitation
  String userId = "bar";
  try{
    await ChatClient.getInstance.contactManager.declineInvitation(userId);
  } on ChatError catch (e) {
  }
  ```

User A uses `ContactEventHandler` to listen for contact events.

* If user B accepts the invitation, `onContactInvited` is triggered.

  ```dart
  class _ContactPageState extends State {
    @override
    void initState() {
      super.initState();
      // Adds the contact event handler.
      ChatClient.getInstance.contactManager.addEventHandler(
        "UNIQUE_HANDLER_ID",
        ContactEventHandler(
          onContactInvited: (userId, reason) {},
        ),
      );
    }
    @override
    void dispose() {
      // Removes the contact event handler.
      ChatClient.getInstance.contactManager.removeEventHandler("UNIQUE_HANDLER_ID");
      super.dispose();
    }
  }
  ```

* If user B declines the invitation, `onFriendRequestDeclined` is triggered.

  ```dart
  class _ContactPageState extends State {
    @override
    void initState() {
      super.initState();
      // Adds the contact event handler.
      ChatClient.getInstance.contactManager.addEventHandler(
        "UNIQUE_HANDLER_ID",
        ContactEventHandler(
          onFriendRequestDeclined: (userId) {},
        ),
      );
    }
    @override
    void dispose() {
      // Removes the contact event handler.
      ChatClient.getInstance.contactManager.removeEventHandler("UNIQUE_HANDLER_ID");
      super.dispose();
    }
  }
  ```

### Retrieve the contact list

You can retrieve the contact list from the server and from the local database. Refer to the following sample code:

```dart
// Call getAllContactsFromServer to retrieve the contact list from the server.
List contacts = await ChatClient.getInstance.contactManager.getAllContactsFromServer();

// Call getAllContactsFromDB to retrieve the contact list from the local database.
List contacts = await ChatClient.getInstance.contactManager.getAllContactsFromDB();
```

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

```dart
// The user ID
String userId = "tom";
// Whether to keep the conversation when deleting the contact
bool keepConversation = true;
try {
  await ChatClient.getInstance.contactManager.deleteContact(
    userId,
    keepConversation,
  );
} on ChatError catch (e) {
}
```

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

```dart
// The user ID
String userId = "tom";
try {
  await ChatClient.getInstance.contactManager.addUserToBlockList(userId);
} on ChatError catch (e) {
}
```

### Retrieve the blocklist

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

```dart
try {
  List list =
      await ChatClient.getInstance.contactManager.getBlockListFromDB();
} on ChatError catch (e) {
}
```

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

```dart
try {
  List list =
      await ChatClient.getInstance.contactManager.getBlockListFromServer();
} on ChatError catch (e) {
}
```

### Remove a user from the blocklist

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

```dart
String userId = "tom";
try {
  await ChatClient.getInstance.contactManager.removeUserFromBlockList(userId);
} on ChatError catch (e) {
}
```