APIs topic

APIs

基准：ZIMKit Flutter v2.0.0（2026-10-14 与源码核对）

This document describes the APIs available in ZIMKit, including initialization, conversation management, messaging, group operations, and user management.

Table of Contents

ZIMKit Singleton

init

  • Description Initializes the ZIMKit SDK with the given app credentials and configuration.

  • Prototype

    Future<void> init({
  required int appID,
  String appSign = '',
  String appSecret = '',
  ZIMKitConfig? config,
  ZIMKitEvents? events,
})

  • Example

    await ZIMKit().init(
  appID: yourAppID,
  appSign: yourAppSign,
  config: ZIMKitConfig(),
  events: ZIMKitEvents(),
);

uninit

  • Description Uninitializes the ZIMKit SDK and releases all resources.

  • Prototype

    Future<void> uninit()

  • Example

    await ZIMKit().uninit();

getVersion

  • Description Returns the current version string of ZIMKit.

  • Prototype

    String getVersion()

  • Example

    final version = ZIMKit().getVersion();
print('ZIMKit version: $version');

Conversation APIs

getConversationListNotifier

  • Description Gets a Future that resolves to a notifier for the conversation list.

  • Prototype

    Future<ZIMKitConversationListNotifier> getConversationListNotifier()

  • Example

    final notifier = await ZIMKit().getConversationListNotifier();

getConversation

  • Description Gets a ValueNotifier for a specific conversation by ID and type.

  • Prototype

    ValueNotifier<ZIMKitConversation> getConversation(
  String id,
  ZIMConversationType type,
)

  • Example

    final conversation = ZIMKit().getConversation('user123', ZIMConversationType.peer);

getTotalUnreadMessageCount

  • Description Gets a notifier for the total unread message count across all conversations.

  • Prototype

    ValueNotifier<int> getTotalUnreadMessageCount()

  • Example

    final unreadCount = ZIMKit().getTotalUnreadMessageCount();

deleteConversation

  • Description Deletes a conversation and optionally its messages.

  • Prototype

    Future<void> deleteConversation(
  String id,
  ZIMConversationType type, {
  bool isAlsoDeleteMessages = false,
  bool isAlsoDeleteFromServer = true,
})

  • Example

    await ZIMKit().deleteConversation(
  'conversation123',
  ZIMConversationType.peer,
  isAlsoDeleteMessages: true,
);

deleteAllConversation

  • Description Deletes all conversations.

  • Prototype

    Future<void> deleteAllConversation({
  bool isAlsoDeleteFromServer = true,
  bool isAlsoDeleteMessages = false,
})

  • Example

    await ZIMKit().deleteAllConversation(isAlsoDeleteMessages: true);

clearUnreadCount

  • Description Clears the unread count for a specific conversation.

  • Prototype

    Future<void> clearUnreadCount(
  String conversationID,
  ZIMConversationType conversationType,
)

  • Example

    await ZIMKit().clearUnreadCount('user123', ZIMConversationType.peer);

loadMoreConversation

  • Description Loads more conversations from the server.

  • Prototype

    Future<int> loadMoreConversation()

  • Example

    final count = await ZIMKit().loadMoreConversation();

getOfflineConversationInfo

  • Description Gets information about offline message cache.

  • Prototype

    Future<ZegoZIMKitOfflineMessageCacheInfo> getOfflineConversationInfo({
  bool selfDestructing = true,
})

  • Example

    final info = await ZIMKit().getOfflineConversationInfo();

updateConversationPinnedState

  • Description Updates the pinned state of a conversation.

  • Prototype

    Future<void> updateConversationPinnedState(
  String conversationID,
  ZIMConversationType conversationType,
  bool isPinned,
)

  • Example

    await ZIMKit().updateConversationPinnedState(
  'conversation123',
  ZIMConversationType.peer,
  true,
);

setConversationNotificationStatus

  • Description Sets the notification status (mute/unmute) for a conversation.

  • Prototype

    Future<void> setConversationNotificationStatus(
  String conversationID,
  ZIMConversationType conversationType,
  ZIMConversationNotificationStatus status,
)

  • Example

    await ZIMKit().setConversationNotificationStatus(
  'conversation123',
  ZIMConversationType.peer,
  ZIMConversationNotificationStatus.notNotify,
);

queryUser

  • Description Queries user information by user ID.

  • Prototype

    Future<ZIMUserFullInfo> queryUser(String userID)

  • Example

    final userInfo = await ZIMKit().queryUser('user123');

Message APIs

getMessageListNotifier

  • Description Gets a notifier for the message list of a specific conversation.

  • Prototype

    Future<ZIMKitMessageListNotifier> getMessageListNotifier(
  String conversationID,
  ZIMConversationType type,
)

  • Example

    final notifier = await ZIMKit().getMessageListNotifier('user123', ZIMConversationType.peer);

getOnMessageReceivedNotifier

  • Description Gets a notifier for receiving new messages.

  • Prototype

    ValueNotifier<ZIMKitReceivedMessages?> getOnMessageReceivedNotifier()

  • Example

    final notifier = ZIMKit().getOnMessageReceivedNotifier();

loadMoreMessage

  • Description Loads more messages for a conversation.

  • Prototype

    Future<int> loadMoreMessage(
  String conversationID,
  ZIMConversationType conversationType,
)

  • Example

    await ZIMKit().loadMoreMessage('user123', ZIMConversationType.peer);

sendTextMessage

  • Description Sends a text message to a conversation.

  • Prototype

    Future<void> sendTextMessage(
  String conversationID,
  ZIMConversationType type,
  String text, {
  ZIMKitMessage? repliedMessage,
  FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
  Function(ZIMKitMessage)? onMessageSent,
})

  • Example

    await ZIMKit().sendTextMessage(
  'user123',
  ZIMConversationType.peer,
  'Hello!',
);

replyMessage

  • Description Replies to a specific message with text.

  • Prototype

    Future<void> replyMessage(
  String conversationID,
  ZIMConversationType type,
  ZIMKitMessage repliedMessage,
  String text, {
  FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
  Function(ZIMKitMessage)? onMessageSent,
})

  • Example

    await ZIMKit().replyMessage(
  'user123',
  ZIMConversationType.peer,
  originalMessage,
  'This is a reply',
);

sendFileMessage

  • Description Sends files sequentially. By default, known image, video, and audio extensions select their matching message type; set autoDetectType to false to send each item as a file message. The optional progress callback reports upload progress for this call.

  • Prototype

    Future<void> sendFileMessage(
  String conversationID,
  ZIMConversationType type,
  List<ZIMKitPlatformFile> files, {
  bool autoDetectType = true,
  ZIMMediaUploadingProgress? mediaUploadingProgress,
  FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
  Function(ZIMKitMessage)? onMessageSent,
})

  • Example

    await ZIMKit().sendFileMessage(
  'user123',
  ZIMConversationType.peer,
  [file],
);

sendMediaMessage

  • Description Sends media messages (images, videos, audio) sequentially. The optional progress callback reports upload progress for this call.

  • Prototype

    Future<void> sendMediaMessage(
  String conversationID,
  ZIMConversationType type,
  List<ZIMKitPlatformFile> files, {
  ZIMMediaUploadingProgress? mediaUploadingProgress,
  FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
  Function(ZIMKitMessage)? onMessageSent,
})

  • Example

    await ZIMKit().sendMediaMessage(
  'user123',
  ZIMConversationType.peer,
  [imageFile],
);

sendCustomMessage

  • Description Sends a custom message with user-defined type and content.

  • Prototype

    Future<void> sendCustomMessage(
  String conversationID,
  ZIMConversationType type, {
  required int customType,
  required String customMessage,
  String? searchedContent,
  FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
  Function(ZIMKitMessage)? onMessageSent,
})

  • Example

    await ZIMKit().sendCustomMessage(
  'user123',
  ZIMConversationType.peer,
  customType: 1001,
  customMessage: '{"action": "like"}',
);

sendCombineMessage

  • Description Sends a combined message containing multiple messages.

  • Prototype

    Future<void> sendCombineMessage(
  String conversationID,
  ZIMConversationType type, {
  required String title,
  required String summary,
  required List<ZIMKitMessage> messageList,
  FutureOr<ZIMKitMessage> Function(ZIMKitMessage)? preMessageSending,
  Function(ZIMKitMessage)? onMessageSent,
})

  • Example

    await ZIMKit().sendCombineMessage(
  'user123',
  ZIMConversationType.peer,
  title: 'Chat History',
  summary: ['Message 1', 'Message 2'],
  messageList: messages,
);

queryCombineMessageDetail

  • Description Queries the detail of a combined message.

  • Prototype

    Future<List<ZIMKitMessage>> queryCombineMessageDetail(
  ZIMKitMessage message,
)

  • Example

    final messages = await ZIMKit().queryCombineMessageDetail(combineMessage);

deleteMessage

  • Description Deletes specified messages from a conversation.

  • Prototype

    Future<void> deleteMessage(List<ZIMKitMessage> messages)

  • Example

    await ZIMKit().deleteMessage([message1, message2]);

deleteAllMessage

  • Description Deletes all messages in a conversation.

  • Prototype

    Future<void> deleteAllMessage({
  required String conversationID,
  required ZIMConversationType conversationType,
  required bool isAlsoDeleteServerMessage,
})

  • Example

    await ZIMKit().deleteAllMessage(
  conversationID: 'user123',
  conversationType: ZIMConversationType.peer,
  isAlsoDeleteServerMessage: true,
);

recallMessage

  • Description Recalls (deletes) a sent message within the time limit.

  • Prototype

    Future<void> recallMessage(ZIMKitMessage message)

  • Example

    await ZIMKit().recallMessage(message);

updateLocalExtendedData

  • Description Updates local extended data for a message.

  • Prototype

    Future<void> updateLocalExtendedData(
  ZIMKitMessage message,
  String localExtendedData,
)

  • Example

    await ZIMKit().updateLocalExtendedData(message, '{"key": "value"}');

addMessageReaction

  • Description Adds a reaction (emoji) to a message.

  • Prototype

    Future<void> addMessageReaction(
  ZIMKitMessage message,
  String reactionType,
)

  • Example

    await ZIMKit().addMessageReaction(message, '👍');

deleteMessageReaction

  • Description Deletes a reaction from a message.

  • Prototype

    Future<void> deleteMessageReaction(
  ZIMKitMessage message,
  String reactionType,
)

  • Example

    await ZIMKit().deleteMessageReaction(message, '👍');

downloadMediaFile

  • Description Downloads media file for a message (image, video, audio, file).

  • Prototype

    void downloadMediaFile(ZIMKitMessage message)

  • Example

    ZIMKit().downloadMediaFile(message);

Group APIs

createGroup

  • Description Creates a new group with the specified name and initial members.

  • Prototype

    Future<String?> createGroup(
  String name,
  List<String> inviteUserIDs, {
  String id = '',
})

  • Example

    final groupID = await ZIMKit().createGroup(
  'My Group',
  ['user1', 'user2'],
);

joinGroup

  • Description Joins an existing group.

  • Prototype

    Future<int> joinGroup(String conversationID)

  • Example

    final errorCode = await ZIMKit().joinGroup('group123');

addUsersToGroup

  • Description Adds users to an existing group.

  • Prototype

    Future<int> addUsersToGroup(
  String conversationID,
  List<String> userIDs,
)

  • Example

    await ZIMKit().addUsersToGroup('group123', ['user4', 'user5']);

removeUsersFromGroup

  • Description Removes users from a group.

  • Prototype

    Future<int> removeUsersFromGroup(
  String conversationID,
  List<String> userIDs,
)

  • Example

    await ZIMKit().removeUsersFromGroup('group123', ['user4']);

leaveGroup

  • Description Leaves a group.

  • Prototype

    Future<int> leaveGroup(String conversationID)

  • Example

    await ZIMKit().leaveGroup('group123');

queryGroupInfo

  • Description Queries group information.

  • Prototype

    ValueNotifier<ZIMKitGroupInfo> queryGroupInfo(String conversationID)

  • Example

    final groupInfo = ZIMKit().queryGroupInfo('group123');

disbandGroup

  • Description Disbands (deletes) a group. Only the group owner can perform this action.

  • Prototype

    Future<int> disbandGroup(String conversationID)

  • Example

    await ZIMKit().disbandGroup('group123');

transferGroupOwner

  • Description Transfers group ownership to another member.

  • Prototype

    Future<int> transferGroupOwner(
  String conversationID,
  String toUserID,
)

  • Example

    await ZIMKit().transferGroupOwner('group123', 'newOwnerID');

queryGroupMemberInfo

  • Description Queries information about a specific group member.

  • Prototype

    Future<ZIMGroupMemberInfo?> queryGroupMemberInfo(
  String conversationID,
  String userID,
)

  • Example

    final memberInfo = await ZIMKit().queryGroupMemberInfo('group123', 'user123');

queryGroupOwner

  • Description Gets a notifier for the group owner information.

  • Prototype

    ValueNotifier<ZIMGroupMemberInfo?> queryGroupOwner(String conversationID)

  • Example

    final owner = ZIMKit().queryGroupOwner('group123');

queryGroupMemberList

  • Description Gets a notifier for the list of group members. onError receives a final query failure after any eligible relogin retry; callers can show an error and retry the query.

  • Prototype

    ListNotifier<ZIMGroupMemberInfo> queryGroupMemberList(
  String conversationID, {void Function(Object error)? onError})

  • Example

    final memberList = ZIMKit().queryGroupMemberList('group123');

queryGroupMemberCount

  • Description Gets a notifier for the count of group members.

  • Prototype

    ValueNotifier<int> queryGroupMemberCount(String conversationID)

  • Example

    final count = ZIMKit().queryGroupMemberCount('group123');

setGroupMemberRole

  • Description Sets the role for a group member.

  • Prototype

    Future<int> setGroupMemberRole({
  required String conversationID,
  required String userID,
  required int role,
})

  • Example

    await ZIMKit().setGroupMemberRole(
  conversationID: 'group123',
  userID: 'user123',
  role: ZIMGroupMemberRole.manager,
);

getGroupStateChangedEventStream

  • Description Gets a stream for group state changed events.

  • Prototype

    Stream<ZIMKitEventGroupStateChanged> getGroupStateChangedEventStream()

  • Example

    ZIMKit().getGroupStateChangedEventStream().listen((event) {
  print('Group state changed: ${event.state}');
});

getGroupNameUpdatedEventStream

  • Description Gets a stream for group name updated events.

  • Prototype

    Stream<ZIMKitEventGroupNameUpdated> getGroupNameUpdatedEventStream()

  • Example

    ZIMKit().getGroupNameUpdatedEventStream().listen((event) {
  print('Group name updated to: ${event.groupName}');
});

getGroupAvatarUrlUpdatedEventStream

  • Description Gets a stream for group avatar URL updated events.

  • Prototype

    Stream<ZIMKitEventGroupAvatarUrlUpdated> getGroupAvatarUrlUpdatedEventStream()

  • Example

    ZIMKit().getGroupAvatarUrlUpdatedEventStream().listen((event) {
  print('Group avatar updated');
});

getGroupNoticeUpdatedEventStream

  • Description Gets a stream for group notice updated events.

  • Prototype

    Stream<ZIMKitEventGroupNoticeUpdated> getGroupNoticeUpdatedEventStream()

  • Example

    ZIMKit().getGroupNoticeUpdatedEventStream().listen((event) {
  print('Group notice updated: ${event.notice}');
});

getGroupAttributesUpdatedEventStream

  • Description Gets a stream for group attributes updated events.

  • Prototype

    Stream<ZIMKitEventGroupAttributesUpdated> getGroupAttributesUpdatedEventStream()

  • Example

    ZIMKit().getGroupAttributesUpdatedEventStream().listen((event) {
  print('Group attributes updated');
});

getGroupMemberStateChangedEventStream

  • Description Gets a stream for group member state changed events (joined/left).

  • Prototype

    Stream<ZIMKitEventGroupMemberStateChanged> getGroupMemberStateChangedEventStream()

  • Example

    ZIMKit().getGroupMemberStateChangedEventStream().listen((event) {
  print('Member ${event.userID} ${event.state}');
});

getGroupMemberInfoUpdatedEventStream

  • Description Gets a stream for group member info updated events.

  • Prototype

    Stream<ZIMKitEventGroupMemberInfoUpdated> getGroupMemberInfoUpdatedEventStream()

  • Example

    ZIMKit().getGroupMemberInfoUpdatedEventStream().listen((event) {
  print('Member info updated: ${event.userID}');
});

User APIs

connectUser

  • Description Connects a user to the ZIM service with the given credentials.

  • Prototype

    Future<int> connectUser({
  required String id,
  String name = '',
  String avatarUrl = '',
  String token = '',
})

  • Example

    await ZIMKit().connectUser(
  id: 'user123',
  name: 'John Doe',
  avatarUrl: 'https://example.com/avatar.png',
  token: tokenFromYourServer,
);

renewToken

  • Description Renews the current login token. Obtain the new token from your server.

  • Prototype

    Future<int> renewToken(String token)

  • Returns Returns 0 on success, or the ZIM error code on failure.

  • Example

    final errorCode = await ZIMKit().renewToken(tokenFromYourServer);
if (errorCode != 0) {
  debugPrint('Token renewal failed: $errorCode');
}

disconnectUser

  • Description Disconnects the current user from the ZIM service.

  • Prototype

    Future<void> disconnectUser()

  • Example

    await ZIMKit().disconnectUser();

currentUser

  • Description Gets the current user's information.

  • Prototype

    ZIMUserFullInfo? currentUser()

  • Example

    final user = ZIMKit().currentUser();

queryUser

  • Description Queries user information by user ID.

  • Prototype

    Future<ZIMUserFullInfo> queryUser(String id)

  • Example

    final userInfo = await ZIMKit().queryUser('user123');

updateUserInfo

  • Description Updates the current user's information.

  • Prototype

    Future<int> updateUserInfo({
  String name = '',
  String avatarUrl = '',
})

  • Example

    await ZIMKit().updateUserInfo(
  name: 'New Name',
  avatarUrl: 'https://example.com/new_avatar.png',
);

getConnectionStateChangedEventStream

  • Description Gets a stream for connection state changed events.

  • Prototype

    Stream<ZegoSignalingPluginConnectionStateChangedEvent> getConnectionStateChangedEventStream()

  • Example

    ZIMKit().getConnectionStateChangedEventStream().listen((event) {
  print('Connection state: ${event.state}');
});

Helper APIs

registerAppLifecycleStateChangedListener

  • Description Registers a message handler for app lifecycle state changes.

  • Prototype

    void registerAppLifecycleStateChangedListener(
  ZegoPluginAdapterMessageHandler listener,
)

  • Example

    ZIMKit().registerAppLifecycleStateChangedListener((message) {
  print('Received message: $message');
});

unregisterAppLifecycleStateChangedListener

  • Description Unregisters a previously registered message handler.

  • Prototype

    void unregisterAppLifecycleStateChangedListener(
  ZegoPluginAdapterMessageHandler listener,
)

  • Example

    ZIMKit().unregisterAppLifecycleStateChangedListener(listener);

isAppLocked

  • Description Checks if the app is currently in a locked state.

  • Prototype

    Future<bool> isAppLocked()

  • Example

    final isLocked = await ZIMKit().isAppLocked();

setForwardMessages

  • Description Sets the messages to be forwarded and the forward type.

  • Prototype

    void setForwardMessages(
  List<ZIMKitMessage> messages,
  ZIMKitForwardType forwardType,
)

  • Example

    ZIMKit().setForwardMessages(messages, ZIMKitForwardType.merge);

getForwardMessages

  • Description Gets the messages currently set for forwarding.

  • Prototype

    List<ZIMKitMessage> getForwardMessages()

  • Example

    final messages = ZIMKit().getForwardMessages();

getForwardType

  • Description Gets the current forward type.

  • Prototype

    ZIMKitForwardType? getForwardType()

  • Example

    final type = ZIMKit().getForwardType();

clearForwardMessages

  • Description Clears the forward messages and resets the forward type.

  • Prototype

    void clearForwardMessages()

  • Example

    ZIMKit().clearForwardMessages();

Classes

ZIMKit Get started APIs Configs Events Migration_v2.x
ZIMKit - Zego Instant Messaging Kit