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

> 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 [#understand-the-tech-1]

    The Chat SDK uses `IAgoraChatContactManager` to add, remove and manage contacts. The following are the core methods:

    * `addContact`: Adds a contact.
    * `deleteContact`: Deletes a contact.
    * `getContactsFromServerWithCompletion`: Retrieves a list of contacts from the server.
    * `addUserToBlackList`: Adds the specified user to the blocklist.
    * `removeUserFromBlackList`: Removes the specified user from the blocklist.
    * `getBlackListFromServerWithCompletion`: Retrieves a list of blocked users from the server.

    ## Prerequisites [#prerequisites-1]

    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 [#implementation-1]

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

    ### Manage the contact list [#manage-the-contact-list-1]

    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 [#send-a-contact-invitation-1]

    Call `addContact` to add the specified user as a contact:

    ```objc
    /*
     *  Adds a contact.
     *
     *  @param aUsername        The username to be added as a contact
     *  @param aMessage         The invitation message
     *  @param aCompletionBlock The completion block of this method
     */
    [[AgoraChatClient sharedClient].contactManager addContact:@"aUsername" message:@"Message" completion:^(NSString *aUsername, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Adding the contact succeeds %@",aUsername);
        } else {
            NSLog(@"Adding the contact fails %@", aError.errorDescription);
        }
    }];
    ```

    #### Listen for contact events [#listen-for-contact-events-1]

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

    ```objc
    // Adds a contact manager delegate
    [[AgoraChatClient sharedClient].contactManager addDelegate:self delegateQueue:nil];
    //Removes the contact manager delegate
    [[AgoraChatClient sharedClient].contactManager removeDelegate:self];

    - (void)friendRequestDidReceiveFromUser:(NSString *)aUsername
                                    message:(NSString *)aMessage
    { }
    // The peer user accepts the contact invitation.
    - (void)friendRequestDidApproveByUser:(NSString *)aUsername
    { }
    // The peer user declines the contact invitation.
    - (void)friendRequestDidDeclineByUser:(NSString *)aUsername
    { }
    // The contact is deleted.
    - (void)friendshipDidRemoveByUser:(NSString *)aUsername
    { }
    ```

    #### Accept or decline the contact invitation [#accept-or-decline-the-contact-invitation-1]

    After receiving `friendRequestDidReceiveFromUser`, call `approveFriendRequestFromUser` or `declineFriendRequestFromUser` to accept or decline the invitation. The peer user receives the `friendRequestDidApprove` or `friendRequestDidDecline` callback.

    ```objc
    /*
     *  Approves the contact invitation.
     *
     *  @param aUsername        The username that sends the contact invitation
     *  @param aCompletionBlock The completion block of this method
     */
    [[AgoraChatClient sharedClient].contactManager approveFriendRequestFromUser:@"aUsername" completion:^(NSString *aUsername, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Approving the contact invitation succeeds");
        } else {
            NSLog(@"Approving the contact invitation fails because of--- %@", aError.errorDescription);
        }
    }];
    ```

    ```objc
    /*
     *  Declines the contact invitation.
     *
     *  @param aUsername        The username that sends the contact invitation
     *  @param aCompletionBlock The completion block of this method
     */
    [[AgoraChatClient sharedClient].contactManager declineFriendRequestFromUser:@"aUsername" completion:^(NSString *aUsername, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Declining the contact invitation succeeds.");
        } else {
            NSLog(@"Declining the contact invitation fails because of %@", aError.errorDescription);
        }
    }];
    ```

    Once you accept or decline the contact invitation, the user that sends the invitation receives the `friendRequestDidApproveByUser` or `friendRequestDidDeclineByUser` callback.

    ```objc
    /*
     * Occurs when the peer user accepts your contact invitation.
     */
    - (void)friendRequestDidApproveByUser:(NSString *)aUsername
    { }
    ```

    ```objc
    /*
     * Occurs when the peer user declines your contact invitation.
     */
    - (void)friendRequestDidDeclineByUser:(NSString *)aUsername
    { }
    ```

    #### Delete a contact [#delete-a-contact-1]

    Call `deleteContact` to delete the specified contact.

    ```objc
    /*
     *  Deletes the contact.
     *
     *  @param aUsername                The username of the contact to be removed
     *  @param aIsDeleteConversation    Whether to delete the conversation with the contact
     *  @param aCompletionBlock         The completion block for this method
     */
    [[AgoraChatClient sharedClient].contactManager deleteContact:@"aUsername" isDeleteConversation:aIsDeleteConversation completion:^(NSString *aUsername, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Removing the contact succeeds");
        } else {
            NSLog(@"Removing the contact fails %@", aError.errorDescription);
        }
    }];
    ```

    Once the contact is deleted, both users receive the `friendshipDidRemoveByUser` callback.

    ```objc
    /*
     * Occurs when the contact is removed.
     */
    - (void)friendshipDidRemoveByUser:(NSString *)aUsername
    { }
    ```

    #### Retrieve the contact list [#retrieve-the-contact-list-1]

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

    ```objc
    // Retrieves a list of contacts from the server
    [[AgoraChatClient sharedClient].contactManager getContactsFromServerWithCompletion:^(NSArray *aList, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Retrieving the contact list succeeds %@",aList);
        } else {
            NSLog(@"Retrieving the contact list fails because of %@", aError.errorDescription);
        }
    }];
    ```

    ```objc
    // Retrieves a list of contacts from the local database
    NSArray *userlist = [[AgoraChatClient sharedClient].contactManager getContacts];
    ```

    ### Manage the blocklist [#manage-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.

    #### Add a user to the blocklist [#add-a-user-to-the-blocklist]

    Call `addUserToBlackList` to add the specified user to the blocklist.

    ```objc
    /*
     *  Adds the user to the blocklist.
     *
     *  @param aUsername        The usernames to be added to the blocklist
     *  @param aCompletionBlock The completion block of this method
     */
    [[AgoraChatClient sharedClient].contactManager addUserToBlackList:@"aUsername" completion:^(NSString *aUsername, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Adding the contact to the blocklist succeeds");
        } else {
            NSLog(@"Adding the contact to the blocklist fails because of %@", aError.errorDescription);
        }
    }];
    ```

    #### Remove a user from the blocklist [#remove-a-user-from-the-blocklist]

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

    ```objc
    /*
     *  Removes the user from the blocklist.
     *
     *  @param aUsername        The usernames to be removed from the blocklist
     *  @param aCompletionBlock The completion block for this method call
     */
    [[AgoraChatClient sharedClient].contactManager removeUserFromBlackList:@"aUsername" completion:^(NSString *aUsername, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Removing the user from the blocklist succeeds");
        } else {
            NSLog(@"Removing the user from the blocklist fails because of %@", aError.errorDescription);
        }
    }];
    ```

    #### Retrieve the blocklist from the server [#retrieve-the-blocklist-from-the-server]

    To get the blocklist, call `getBlackListFromServerWithCompletion` to retrieve a list of blocked users from the server.

    ```objc
    /*
     *  Retrieve the blocklist fromn server
     */
    [[AgoraChatClient sharedClient].contactManager getBlackListFromServerWithCompletion:^(NSArray *aList, AgoraChatError *aError) {
        if (!aError) {
            NSLog(@"Retrieving the blocklist from server succeeds %@",aList);
        } else {
            NSLog(@"Retrieving the blocklist from server fails %@", aError.errorDescription);
        }
    }];
    ```

    After retrieving the blocklist from the server, you can also call `getBlackList` to retrieve the blocklist from the local database.

    ```objc
    NSArray *blockList = [[AgoraChatClient sharedClient].contactManager getBlackList];
    ```