Docs Overview/
Chat/
SDK/
Android/
Conversation/
Conversation Group/

Conversation Group

Overview

In some cases, you may need to group conversations, for example, into a "Product experience" or "R&D" group, which can be implemented through the following API.
Note
To use this feature, you need to purchase Premium edition.
This feature is available only in SDK enhanced edition v6.5.2803 or later.

Effect

Using this feature, you can achieve the following conversation group effects in your App:




API Description

Creating a Conversation Group

Call the createConversationGroup API (Android / iOS and macOS / Windows) to create a conversation group.
Note
Up to 20 conversation groups can be created. After this limit is exceeded, the 51010 error will be reported. Groups that are no longer used should be promptly deleted.
Attribute
Definition
Description
groupName
Conversation group name
It must be greater than 0 in length and can contain up to 32 bytes; otherwise, the 51011 error will be reported.
conversationIDList
List of conversation IDs
It cannot be empty.
Sample code:
Android
iOS and macOS
Windows
List<String> conversationIDList = new ArrayList<>();
conversationIDList.add("c2c_user1");
V2TIMManager.getConversationManager().createConversationGroup("conversation_group", conversationIDList, new V2TIMValueCallback<List<V2TIMConversationOperationResult>>() {
    @Override
    public void onSuccess(List<V2TIMConversationOperationResult> v2TIMConversationOperationResults) {
        // Created the conversation group successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to create the conversation group
    }
});
// Create a conversation group
[[V2TIMManager sharedInstance] createConversationGroup:@"conversation_group" conversationIDList:@[@"c2c_yahaha"] succ:^(NSArray<V2TIMConversationOperationResult *> *result) {
    // Created the conversation group successfully
} fail:^(int code, NSString *desc) {
    // Failed to create the conversation 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"conversation_group";
V2TIMStringVector conversationIDList;
conversationIDList.PushBack(u8"c2c_user1");

auto callback = new ValueCallback<V2TIMConversationOperationResultVector>{};
callback->SetCallback(
    [=](const V2TIMConversationOperationResultVector& conversationOperationResultList) {
        // Created the conversation group successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to create the conversation group
        delete callback;
    });

V2TIMManager::GetInstance()->GetConversationManager()->CreateConversationGroup(groupName, conversationIDList,
                                                                               callback);

Deleting a Conversation Group

Call the deleteConversationGroup API (Android / iOS and macOS / Windows) to delete a conversation group.
Note
If the target conversation group doesn't exist, the 51009 error will be reported.
Sample code:
Android
iOS and macOS
Windows
V2TIMManager.getConversationManager().deleteConversationGroup("conversation_group", new V2TIMCallback() {
    @Override
    public void onSuccess() {
        // Deleted the conversation group successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to delete the conversation group
    }
});
// Delete the conversation group
[[V2TIMManager sharedInstance] deleteConversationGroup:@"conversation_group" succ:^{
        // Deleted the conversation group successfully
} fail:^(int code, NSString *desc) {
        // Failed to delete the conversation 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 groupName = u8"conversation_group";

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

V2TIMManager::GetInstance()->GetConversationManager()->DeleteConversationGroup(groupName, callback);

Renaming a Conversation Group

Call the renameConversationGroup API (Android / iOS and macOS / Windows) to rename a conversation group.
Sample code:
Android
iOS and macOS
Windows
V2TIMManager.getConversationManager().renameConversationGroup("conversation_group", "conversation_group_rename", new V2TIMCallback() {
    @Override
    public void onSuccess() {
        // Renamed the conversation group successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to rename the conversation group
    }
});
// Rename a conversation group
[[V2TIMManager sharedInstance] renameConversationGroup:@"conversation_group" newName:@"conversation_group_rename" succ:^{
        // Renamed the conversation group successfully
} fail:^(int code, NSString *desc) {
        // Failed to rename the conversation 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"conversation_group";
V2TIMString newName = u8"conversation_group_rename";

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

V2TIMManager::GetInstance()->GetConversationManager()->RenameConversationGroup(oldName, newName, callback);

Getting the List of Conversation Groups

Call the getConversationGroupList API (Android / iOS and macOS / Windows) to get the list of conversation groups.
Sample code:
Android
iOS and macOS
Windows
V2TIMManager.getConversationManager().getConversationGroupList(new V2TIMValueCallback<List<String>>() {
    @Override
    public void onSuccess(List<String> strings) {
        // Obtained the group list successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to obtain the group list
    }
});
// Get the list of conversation groups
[[V2TIMManager sharedInstance] getConversationGroupList:^(NSArray<NSString *> *groupList) {
    // Obtained the group list successfully
} fail:^(int code, NSString *desc) {
    // Failed to obtain the group list
}];
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_;
};

auto callback = new ValueCallback<V2TIMStringVector>{};
callback->SetCallback(
    [=](const V2TIMStringVector& stringList) {
        // Obtained the group list successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to obtain the group list
        delete callback;
    });

V2TIMManager::GetInstance()->GetConversationManager()->GetConversationGroupList(callback);
Call the getConversationListByFilter API (Android / iOS and macOS / Windows) to get the list of conversations in a group.
Sample code:
Android
iOS and macOS
Windows
V2TIMConversationListFilter filter = new V2TIMConversationListFilter();
filter.setGroupName("conversation_group");
filter.setCount(50);
filter.setNextSeq(0);
V2TIMManager.getConversationManager().getConversationListByFilter(filter, new V2TIMValueCallback<V2TIMConversationResult>() {
    @Override
    public void onSuccess(V2TIMConversationResult v2TIMConversationResult) {
        // Conversation list obtained successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to obtain the conversation list
    }
});
// Pull a specified marked conversation
V2TIMConversationListFilter *filter = [[V2TIMConversationListFilter alloc] init];
filter.groupName = @"conversation_group";
filter.count = 50;
filter.nextSeq = 0;
[[V2TIMManager sharedInstance] getConversationListByFilter:filter succ:^(NSArray<V2TIMConversation *> *list, uint64_t nextSeq, BOOL isFinished) {
   // Obtained the conversation list successfully. `list` is the conversation list.
} fail:^(int code, NSString *desc) {
   // Failed to obtain the conversation list
}];
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_;
};

V2TIMConversationListFilter filter;
filter.nextSeq = 0;
filter.count = 50;
filter.groupName = u8"conversation_group";

auto callback = new ValueCallback<V2TIMConversationResult>{};
callback->SetCallback(
    [=](const V2TIMConversationResult& conversationResult) {
        // Conversation list obtained successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to obtain the conversation list
        delete callback;
    });

V2TIMManager::GetInstance()->GetConversationManager()->GetConversationListByFilter(filter, callback);

Adding a Conversation to a Group

After creating a group, you can call the addConversationsToGroup API (Android / iOS and macOS / Windows) to add a conversation to the group.
Sample code:
Android
iOS and macOS
Windows
List<String> conversationIDList = new ArrayList<>();
conversationIDList.add("c2c_user2");
V2TIMManager.getConversationManager().addConversationsToGroup("conversation_group", conversationIDList, new V2TIMValueCallback<List<V2TIMConversationOperationResult>>() {
    @Override
    public void onSuccess(List<V2TIMConversationOperationResult> v2TIMConversationOperationResults) {
        // Added the conversation to the group successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to add the conversation to the group
    }
});
// Add a conversation to a group
[[V2TIMManager sharedInstance] addConversationsToGroup:@"conversation_group" conversationIDList:@[@"c2c_yahaha"] succ:^(NSArray<V2TIMConversationOperationResult *> *result) {
    // Added the conversation to the group successfully
} fail:^(int code, NSString *desc) {
    // Failed to add the conversation to the 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"conversation_group";
V2TIMStringVector conversationIDList;
conversationIDList.PushBack(u8"c2c_user1");

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

V2TIMManager::GetInstance()->GetConversationManager()->AddConversationsToGroup(groupName, conversationIDList,
                                                                               callback);

Deleting a Conversation from a Group

Call the deleteConversationsFromGroup API (Android / iOS and macOS / Windows) to delete a conversation from a group.
Sample code:
Android
iOS and macOS
Windows
List<String> conversationIDList = new ArrayList<>();
conversationIDList.add("c2c_user2");
V2TIMManager.getConversationManager().deleteConversationsFromGroup("conversation_group", conversationIDList, new V2TIMValueCallback<List<V2TIMConversationOperationResult>>() {
    @Override
    public void onSuccess(List<V2TIMConversationOperationResult> v2TIMConversationOperationResults) {
        // Deleted the conversation from the group successfully
    }

    @Override
    public void onError(int code, String desc) {
        // Failed to delete the conversation from the group
    }
});
// Delete a conversation from a group
[[V2TIMManager sharedInstance] deleteConversationsFromGroup:@"conversation_group" conversationIDList:@[@"c2c_yahaha"] succ:^(NSArray<V2TIMConversationOperationResult *> *result) {
    // Deleted the conversation from the group successfully
} fail:^(int code, NSString *desc) {
    // Failed to delete the conversation from the 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"conversation_group";
V2TIMStringVector conversationIDList;
conversationIDList.PushBack(u8"c2c_user1");

auto callback = new ValueCallback<V2TIMConversationOperationResultVector>{};
callback->SetCallback(
    [=](const V2TIMConversationOperationResultVector& conversationOperationResultList) {
        // Deleted the conversation from the group successfully
        delete callback;
    },
    [=](int error_code, const V2TIMString& error_message) {
        // Failed to delete the conversation from the group
        delete callback;
    });

V2TIMManager::GetInstance()->GetConversationManager()->DeleteConversationsFromGroup(
    groupName, conversationIDList, callback);

Conversation Group Changed Notification

Call the addConversationListener API (Android / iOS and macOS / Windows) to listen for the notification of a conversation group change.
Sample code:
Android
iOS and macOS
Windows
V2TIMConversationListener listener = new V2TIMConversationListener() {
    @Override
    public void onConversationGroupCreated(String groupName, List<V2TIMConversation> conversationList) {
        // Received the notification of conversation group creation
    }

    @Override
    public void onConversationGroupDeleted(String groupName) {
        // Received the notification of conversation group deletion
    }

    @Override
    public void onConversationGroupNameChanged(String oldName, String newName) {
        // Received the notification of conversation group renaming
    }

    @Override
    public void onConversationsAddedToGroup(String groupName, List<V2TIMConversation> conversationList) {
        // Received the notification of a conversation added to a group
    }

    @Override
    void OnConversationsDeletedFromGroup(const V2TIMString& groupName,
                                         const V2TIMConversationVector& conversationList,
                                         uint32_t reason) override {
        // Received the notification of a conversation deleted from a group
        // reason : Indicates the reason why the conversation was deleted from the conversation group, its values are:
        // When reason is 0, it means that it is triggered by the user actively calling deleteConversationsFromGroup.
        // When reason is 1, it means that the number of conversations added to the conversation group exceeds 1000, and the earliest conversation added to the group will be eliminated.
        // When the number of conversations exceeds the limit, adding a new conversation to the group will result in an error. If you want to add the conversation successfully and eliminate the oldest conversation, please submit a ticket to contact customer service for configuration
    }
};
V2TIMManager.getConversationManager().addConversationListener(listener);
[[V2TIMManager sharedInstance] addConversationListener:self];
- (void)onConversationGroupCreated:(NSString *)groupName conversationList:(NSArray<V2TIMConversation *> *)conversationList {
    // Received the notification of conversation group creation
}
- (void)onConversationGroupDeleted:(NSString *)groupName {
    // Received the notification of conversation group deletion
}
- (void)onConversationGroupNameChanged:(NSString *)oldName newName:(NSString *)newName {
    // Received the notification of conversation group renaming
}
- (void)onConversationsAddedToGroup:(NSString *)groupName conversationList:(NSArray<V2TIMConversation *> *)conversationList {
    // Received the notification of a conversation added to a group
}
- (void)onConversationsDeletedFromGroup:(NSString *)groupName conversationList:(NSArray<V2TIMConversation *> *)conversationList reason:(uint32_t)reason {
    // Received the notification of a conversation deleted from a group
    // reason : Indicates the reason why the conversation was deleted from the conversation group, its values are:
    // When reason is 0, it means that it is triggered by the user actively calling deleteConversationsFromGroup.
    // When reason is 1, it means that the number of conversations added to the conversation group exceeds 1000, and the earliest conversation added to the group will be eliminated.
}
class ConversationListener final : public V2TIMConversationListener {
public:
    ConversationListener() = default;
    ~ConversationListener() override = default;

    void OnConversationGroupCreated(const V2TIMString& groupName,
                                    const V2TIMConversationVector& conversationList) override {
        // Received the notification of conversation group creation
    }

    void OnConversationGroupDeleted(const V2TIMString& groupName) override {
        // Received the notification of conversation group deletion
    }

    void OnConversationGroupNameChanged(const V2TIMString& oldName, const V2TIMString& newName) override {
        // Received the notification of conversation group renaming
    }

    void OnConversationsAddedToGroup(const V2TIMString& groupName,
                                     const V2TIMConversationVector& conversationList) override {
        // Received the notification of a conversation added to a group
    }

    void OnConversationsDeletedFromGroup(const V2TIMString& groupName,
                                         const V2TIMConversationVector& conversationList,
                                         uint32_t reason) override {
        // Received the notification of a conversation deleted from a group
        // reason : Indicates the reason why the conversation was deleted from the conversation group, its values are:
        // When reason is 0, it means that it is triggered by the user actively calling deleteConversationsFromGroup.
        // When reason is 1, it means that the number of conversations added to the conversation group exceeds 1000, and the earliest conversation added to the group will be eliminated.
    }
};

// Add a conversation event listener. Keep `conversationListener` valid before the listener is removed to ensure event callbacks are received.
ConversationListener conversationListener;
V2TIMManager::GetInstance()->GetConversationManager()->AddConversationListener(&conversationListener);