please select
  • UIKit
  • SDK
  • Server APIs
Chat/
SDK/
Android/
User/
SDK
  • Install Chat SDK
  • Initialize Chat SDK
  • Login and Logout
  • Message
    • Overview
    • Send a Message
    • Receive a Message
    • Retrieve Messages
    • Forward Messages
    • Modify a Message
    • Insert a Message
    • Delete Messages
    • Clear History Messages
    • Recall a Message
    • Send an Online Message
    • Message Read Receipt
    • Query Messages
    • Mentions
    • Targeted Group Message
    • Do not Notify
    • Key-Value Extensions
    • Reactions
    • Translation
    • Pin Messages
  • Conversation
    • Overview
    • Conversation List
    • Get Conversations
    • Unread Count
    • Pin Conversations
    • Delete Conversations
    • Draft
    • Mark
    • Conversation Group
  • Group
    • Overview
    • Manage Group
    • Profile
    • Manage Members
    • Member Profile
    • Attribute
    • Counter
  • Community and Topic
    • Manage Community
    • Permission Group
  • User
    • User Profile
    • User Status
    • Manage Friends
    • Friend Group
    • Block Lists
    • Follow
  • Local Search
    • Search Messages
    • Search Friends
    • Search Groups
    • Search Group Members
  • Signaling
  • API Reference
    • Java
  • Guideline for Beginners
  • Console Guide
    • Creating and Upgrading an Application
    • Basic Configuration
    • Feature Configuration
    • Account Management
    • Group Management
    • Webhook Configuration
  • Product Introduction
    • Message Management
      • One-to-One Message
      • Message Storage
      • Offline Push
      • Group Message
      • Message Formats
    • Account System
      • Login Authentication
      • Online Status Management
    • Group Related
      • Group System
      • Group Management
    • User Profile and Relationship Chain
      • Profile Management
      • Relationship Chain Management
  • Purchase Guide
    • Billing Overview
    • Pricing
  • Error Codes
Docs Overview/
Chat/
SDK/
Android/
User/
Friend Group/

Friend Group

Overview

To group friends into categories such as "classmates" and "coworkers", call the following APIs.

Creating a friend group

Call the createFriendGroup API (Android / iOS and Mac / Windows) to create a friend group.
Sample code:
Android
iOS and macOS
Windows
List<String> userIDList = new ArrayList<>();
userIDList.add("user1");
userIDList.add("user2");
V2TIMManager.getFriendshipManager().createFriendGroup("Friends at university", userIDList, new V2TIMValueCallback<List<V2TIMFriendOperationResult>>() {
  @Override
  public void onSuccess(List<V2TIMFriendOperationResult> v2TIMFriendOperationResults) {
    // Friend group created successfully
  }

  @Override
  public void onError(int code, String desc) {
    // Failed to create the friend group
  }
});
// Create a friend group
[[V2TIMManager sharedInstance] createFriendGroup:@"Friends at university" userIDList:@[@"user1", @"user2"] succ:^(NSArray<V2TIMFriendOperationResult *> *resultList) {
    // Friend group created successfully
} fail:^(int code, NSString *desc) {
    // Failed to create the friend group
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
    using SuccessCallback = std::function<void(const T&)>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;

    ValueCallback() = default;
    ~ValueCallback() override = default;

    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
        success_callback_ = std::move(success_callback);
        error_callback_ = std::move(error_callback);
    }

    void OnSuccess(const T& value) override {
        if (success_callback_) {
            success_callback_(value);
        }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
        if (error_callback_) {
            error_callback_(error_code, error_message);
        }
    }

private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
};

V2TIMString groupName = u8"Friends at university";
V2TIMStringVector userIDList;
userIDList.PushBack(u8"user1");
userIDList.PushBack(u8"user2");

auto callback = new ValueCallback<V2TIMFriendOperationResultVector>{};
callback->SetCallback(
    [=](const V2TIMFriendOperationResultVector& friendOperationResultList) {
        // Friend group created successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to create the friend group
        delete callback;
    });

V2TIMManager::GetInstance()->GetFriendshipManager()->CreateFriendGroup(groupName, userIDList, callback);

Deleting a friend group

Call the deleteFriendGroup API (Android / iOS and Mac / Windows) to delete a friend group. This will not delete the friends.
Sample code:
Android
iOS and macOS
Windows
List<String> friendGroupList = new ArrayList<>();
friendGroupList.add("Friends at university");
V2TIMManager.getFriendshipManager().deleteFriendGroup(friendGroupList, new V2TIMCallback() {
  @Override
  public void onSuccess() {
    // Friend group deleted successfully
  }

  @Override
  public void onError(int code, String desc) {
    // Failed to delete the friend group
  }
});
// Delete a friend group
[[V2TIMManager sharedInstance] deleteFriendGroup:@[@"Friends at university"] succ:^{
    // Friend list deleted successfully
} fail:^(int code, NSString *desc) {
    // Failed to delete the friend group
}];
class Callback final : public V2TIMCallback {
public:
    using SuccessCallback = std::function<void()>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;

    Callback() = default;
    ~Callback() override = default;

    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
        success_callback_ = std::move(success_callback);
        error_callback_ = std::move(error_callback);
    }

    void OnSuccess() override {
        if (success_callback_) {
            success_callback_();
        }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
        if (error_callback_) {
            error_callback_(error_code, error_message);
        }
    }

private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
};

V2TIMStringVector groupNameList;
groupNameList.PushBack(u8"Friends at university");

auto callback = new Callback{};
callback->SetCallback(
    [=]() {
        // Friend group deleted successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to delete the friend group
        delete callback;
    });

V2TIMManager::GetInstance()->GetFriendshipManager()->DeleteFriendGroup(groupNameList, callback);

Renaming a friend group

Call the renameFriendGroup API (Android / iOS and Mac / Windows) to rename a friend group.
Sample code:
Android
iOS and macOS
Windows
V2TIMManager.getFriendshipManager().renameFriendGroup("Friends at university", "Friends in high school", new V2TIMCallback() {
  @Override
  public void onSuccess() {
    // Friend group name changed successfully
  }

  @Override
  public void onError(int code, String desc) {
    // Failed to rename the friend group
  }
});
// Rename a friend group
[[V2TIMManager sharedInstance] renameFriendGroup:@"Friends at university" newName:@"Friends in high school" succ:^{
    // Friend group name changed successfully
} fail:^(int code, NSString *desc) {
    // Failed to rename the friend group
}];
class Callback final : public V2TIMCallback {
public:
    using SuccessCallback = std::function<void()>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;

    Callback() = default;
    ~Callback() override = default;

    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
        success_callback_ = std::move(success_callback);
        error_callback_ = std::move(error_callback);
    }

    void OnSuccess() override {
        if (success_callback_) {
            success_callback_();
        }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
        if (error_callback_) {
            error_callback_(error_code, error_message);
        }
    }

private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
};

V2TIMString oldName = u8"Friends at university";
V2TIMString newName = u8"Friends in high school";

auto callback = new Callback{};
callback->SetCallback(
    [=]() {
        // Friend group name changed successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to rename the friend group
        delete callback;
    });

V2TIMManager::GetInstance()->GetFriendshipManager()->RenameFriendGroup(oldName, newName, callback);

Getting a friend group

Call the getFriendGroupList API (Android / iOS and Mac / Windows) to get a friend group.
Sample code:
Android
iOS and macOS
Windows
List<String> friendGroups = new ArrayList<>();
friendGroups.add("Friends at university");
V2TIMManager.getFriendshipManager().getFriendGroups(friendGroups, new V2TIMValueCallback<List<V2TIMFriendGroup>>() {
  @Override
  public void onSuccess(List<V2TIMFriendGroup> v2TIMFriendGroups) {
    // Friend group obtained successfully
  }

  @Override
  public void onError(int code, String desc) {
    // Failed to obtain the friend group
  }
});
// Get a friend group
[[V2TIMManager sharedInstance] getFriendGroupList:@[@"Friends at university"] succ:^(NSArray<V2TIMFriendGroup *> *groups) {
    // Friend group obtained successfully
} fail:^(int code, NSString *desc) {
    // Failed to obtain the friend group
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
    using SuccessCallback = std::function<void(const T&)>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;

    ValueCallback() = default;
    ~ValueCallback() override = default;

    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
        success_callback_ = std::move(success_callback);
        error_callback_ = std::move(error_callback);
    }

    void OnSuccess(const T& value) override {
        if (success_callback_) {
            success_callback_(value);
        }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
        if (error_callback_) {
            error_callback_(error_code, error_message);
        }
    }

private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
};

V2TIMStringVector groupNameList;
groupNameList.PushBack(u8"Friends at university");

auto callback = new ValueCallback<V2TIMFriendGroupVector>{};
callback->SetCallback(
    [=](const V2TIMFriendGroupVector& friendGroupList) {
        // Friend group obtained successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to obtain the friend group
        delete callback;
    });

V2TIMManager::GetInstance()->GetFriendshipManager()->GetFriendGroups(groupNameList, callback);

Adding a friend to a friend group

Call the addFriendsToFriendGroup API (Android / iOS and Mac / Windows) to add a friend to a friend group.
Sample code:
Android
iOS and macOS
Windows
List<String> userIDList = new ArrayList<>();
userIDList.add("user1");
userIDList.add("user2");
V2TIMManager.getFriendshipManager().addFriendsToFriendGroup("Friends at university", userIDList, new V2TIMValueCallback<List<V2TIMFriendOperationResult>>() {
  @Override
  public void onSuccess(List<V2TIMFriendOperationResult> v2TIMFriendOperationResults) {
    // Added successfully
  }

  @Override
  public void onError(int code, String desc) {
    // Failed to add
  }
});
// Add a friend to a friend group
[[V2TIMManager sharedInstance] addFriendsToFriendGroup:@"Friends at university" userIDList:@[@"user1", @"user2"] succ:^(NSArray<V2TIMFriendOperationResult *> *resultList) {
    // Added successfully
} fail:^(int code, NSString *desc) {
    // Failed to add
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
    using SuccessCallback = std::function<void(const T&)>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;

    ValueCallback() = default;
    ~ValueCallback() override = default;

    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
        success_callback_ = std::move(success_callback);
        error_callback_ = std::move(error_callback);
    }

    void OnSuccess(const T& value) override {
        if (success_callback_) {
            success_callback_(value);
        }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
        if (error_callback_) {
            error_callback_(error_code, error_message);
        }
    }

private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
};

V2TIMString groupName = u8"Friends at university";
V2TIMStringVector userIDList;
userIDList.PushBack(u8"user1");
userIDList.PushBack(u8"user2");

auto callback = new ValueCallback<V2TIMFriendOperationResultVector>{};
callback->SetCallback(
    [=](const V2TIMFriendOperationResultVector& friendOperationResultList) {
        // Added successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to add
        delete callback;
    });

V2TIMManager::GetInstance()->GetFriendshipManager()->AddFriendsToFriendGroup(groupName, userIDList, callback);

Removing a friend from a friend group

Call deleteFriendsFromFriendGroup API (Android / iOS and Mac / Windows) to remove a friend from a friend group. This will only remove the friend from the friend group and will not delete the friend.
Sample code:
Android
iOS and macOS
Windows
List<String> userIDList = new ArrayList<>();
userIDList.add("user1");
userIDList.add("user2");
V2TIMManager.getFriendshipManager().deleteFriendsFromFriendGroup("Friends at university", userIDList, new V2TIMValueCallback<List<V2TIMFriendOperationResult>>() {
  @Override
  public void onSuccess(List<V2TIMFriendOperationResult> v2TIMFriendOperationResults) {
    // Deleted successfully
  }

  @Override
  public void onError(int code, String desc) {
    // Failed to delete
  }
});
// Remove a friend from a friend group
[[V2TIMManager sharedInstance] deleteFriendsFromFriendGroup:@"Friends at university" userIDList:@[@"user1", @"user2"] succ:^(NSArray<V2TIMFriendOperationResult *> *resultList) {
    // Deleted successfully
} fail:^(int code, NSString *desc) {
    // Failed to delete
}];
template <class T>
class ValueCallback final : public V2TIMValueCallback<T> {
public:
    using SuccessCallback = std::function<void(const T&)>;
    using ErrorCallback = std::function<void(int, const V2TIMString&)>;

    ValueCallback() = default;
    ~ValueCallback() override = default;

    void SetCallback(SuccessCallback success_callback, ErrorCallback error_callback) {
        success_callback_ = std::move(success_callback);
        error_callback_ = std::move(error_callback);
    }

    void OnSuccess(const T& value) override {
        if (success_callback_) {
            success_callback_(value);
        }
    }
    void OnError(int error_code, const V2TIMString& error_message) override {
        if (error_callback_) {
            error_callback_(error_code, error_message);
        }
    }

private:
    SuccessCallback success_callback_;
    ErrorCallback error_callback_;
};

V2TIMString groupName = u8"Friends at university";
V2TIMStringVector userIDList;
userIDList.PushBack(u8"user1");
userIDList.PushBack(u8"user2");

auto callback = new ValueCallback<V2TIMFriendOperationResultVector>{};
callback->SetCallback(
    [=](const V2TIMFriendOperationResultVector& friendOperationResultList) {
        // Deleted successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to delete
        delete callback;
    });

V2TIMManager::GetInstance()->GetFriendshipManager()->DeleteFriendsFromFriendGroup(groupName, userIDList,
                                                                                  callback);

Friend group changed notification

Call the addFriendListener (Android / iOS & Mac / Windows) to listen for the notification of a friend group change.
Sample code:
Android
iOS & Mac
Windows
V2TIMFriendshipListener v2TIMFriendshipListener = new V2TIMFriendshipListener() {
    @Override
    public void onFriendGroupCreated(String groupName, List<V2TIMFriendInfo> friendInfoList) {
        // Received the notification of friend group creation
    }

    @Override
    public void onFriendGroupDeleted(List<String> groupNameList) {
        // Received the notification of friend group deletion
    }

    @Override
    public void onFriendGroupNameChanged(String oldGroupName, String newGroupName) {
        // Received the notification of friend group renaming
    }

    @Override
    public void onFriendsAddedToGroup(String groupName, List<V2TIMFriendInfo> friendInfoList) {
        // Received the notification of a friend added to a group
    }

    @Override
    public void onFriendsDeletedFromGroup(String groupName, List<String> friendIDList) {
        // Received the notification of a friend deleted from a group
    }
};

// Add a relationship listener
V2TIMManager.getFriendshipManager().addFriendListener(v2TIMFriendshipListener);
// Add a relationship listener
[[V2TIMManager sharedInstance] addFriendListener:self];

- (void)onFriendGroupCreated:(NSString *)groupName friendInfoList:(NSArray<V2TIMFriendInfo *> *)friendInfoList {
    // Received the notification of friend group creation
}

- (void)onFriendGroupDeleted:(NSArray<NSString *> *)groupNameList {
    // Received the notification of friend group deletion
}


- (void)onFriendGroupNameChanged:(NSString *)oldGroupName newGroupName:(NSString *)newGroupName {
    // Received the notification of friend group renaming
}

- (void)onFriendsAddedToGroup:(NSString *)groupName friendInfoList:(NSArray<V2TIMFriendInfo *> *)friendInfoList {
    // Received the notification of a friend added to a group
}

- (void)onFriendsDeletedFromGroup:(NSString *)groupName friendIDList:(NSArray<NSString *> *)friendIDList {
    // Received the notification of a friend deleted from a group
}
class FriendshipListener final : public V2TIMFriendshipListener {
public:
    FriendshipListener() = default;
    ~FriendshipListener() override = default;

    void OnFriendGroupCreated(const V2TIMString &groupName, const V2TIMFriendInfoVector &friendInfoList) override {
        // Received the notification of friend group creation
    }

    void OnFriendGroupDeleted(const V2TIMStringVector &groupNameList) override {
        // Received the notification of friend group deletion
    }

    void OnFriendGroupNameChanged(const V2TIMString &oldGroupName, const V2TIMString &newGroupName) override {
        // Received the notification of a friend added to a group
    }

    void OnFriendsAddedToGroup(const V2TIMString &groupName, const V2TIMFriendInfoVector &friendInfoList) override {
        // Received the notification of a friend added to a group
    }

    void OnFriendsDeletedFromGroup(const V2TIMString &groupName, const V2TIMStringVector &friendIDList) override {
        // Received the notification of a friend deleted from a group
    }

    // Other members ...
};

// Add a relationship event listener. Keep `friendshipListener` valid before the listener is removed to ensure event callbacks are received.
SDKListener sdkListener;
FriendshipListener friendshipListener;
V2TIMManager::GetInstance()->GetFriendshipManager()->AddFriendListener(&friendshipListener);
Note
Friend group changed notification is supported only by the Enhanced SDK v8.0 or higher.