SDKsuni-app / uni-app xEnterprise

Conversation group overview

Understand conversation group models, capabilities, and event synchronization workflows.

Conversation groups (tabs / custom categories) are a Commercial Edition feature used to organize the authenticated user's conversation list into segmented categories such as "Work", "Unread", or "Follow-up". A conversation group manages the mapping between a category and a collection of conversationID entries; it does not create chat groups, invite members, or change message destinations.

Group types

Creating and querying conversation groups use different enums and values:

Enum value	Numeric value	Description
`OpenIMConversationGroupTypeNormal`	`0`	Standard custom conversation group created and managed by the user (corresponds to `OpenIMConversationGroupQueryTypeNormal` during queries).
`OpenIMConversationGroupTypeFilter`	`1`	Filtered group maintained by server or SDK rules (corresponds to `OpenIMConversationGroupQueryTypeFilter` during queries).
`OpenIMConversationGroupQueryTypeAll`	`2`	Used strictly when querying all group types; cannot be passed when creating groups.

When creating a group, conversationGroupType accepts 0 | 1; when querying groups, pass 0 | 1 | 2. Filtered group rules depend on your server deployment; do not fabricate synthetic system groups on the client based solely on name strings.

Group data fields

The OpenIMConversationGroupItem structure represents a conversation category. Fields may be null; always check for existence before accessing, and use conversationGroupID as the stable merge key:

Field	Type	Description
`conversationGroupID`	`string \| null`	Unique identifier of the conversation group.
`name`	`string \| null`	Display name of the group.
`order`	`number \| null`	Sequence order index; sorting criteria is defined by application convention.
`conversationGroupType`	`OpenIMConversationGroupQueryType \| null`	Conversation group category type.
`hidden`	`boolean \| null`	Whether the group tab is hidden.
`unreadCount`	`number \| null`	Aggregate unread count across all conversations within this group at query time.
`conversationIDs`	`string[] \| null`	Array of conversation IDs currently assigned to this group.
`createTime`	`number \| null`	Creation timestamp in Unix milliseconds.
`ex`	`string \| null`	Custom application extension string.

Available operations

Listen for group changes

Subscribe centrally to the five conversation group lifecycle events. All five callbacks receive a string signal payload. Treat these events as invalidation triggers to re-query the latest group data and merge updates using conversationGroupID.

import {
  off,
  onConversationGroupAdded,
  onConversationGroupChanged,
  onConversationGroupDeleted,
  onConversationGroupMemberAdded,
  onConversationGroupMemberDeleted,
} from '@/uni_modules/unix-openim-sdk'

const handleConversationGroupRefresh = (_payload: string) => {
  reloadConversationGroups()
}

const groupAddedSubscription = onConversationGroupAdded(
  handleConversationGroupRefresh,
)
const groupChangedSubscription = onConversationGroupChanged(
  handleConversationGroupRefresh,
)
const groupDeletedSubscription = onConversationGroupDeleted(
  handleConversationGroupRefresh,
)
const groupMemberAddedSubscription = onConversationGroupMemberAdded(
  handleConversationGroupRefresh,
)
const groupMemberDeletedSubscription = onConversationGroupMemberDeleted(
  handleConversationGroupRefresh,
)

function removeConversationGroupListeners() {
  off(groupAddedSubscription)
  off(groupChangedSubscription)
  off(groupDeletedSubscription)
  off(groupMemberAddedSubscription)
  off(groupMemberDeletedSubscription)
}

Debounce or coalesce query requests triggered by these events to avoid redundant database lookups under burst event conditions. Unregister the listeners when unmounting components, logging out, or destroying the conversation group state controller.

Was this page helpful?