ZIM Upgrade Guide

This document describes notes and considerations when upgrading the ZIM Web SDK version.

3.1.0 Upgrade Guide

Newly deprecated APIs

queryGroupMessageReceiptReadMemberList and queryGroupMessageReceiptUnreadMemberList have been deprecated since version 3.1.0. To query the member list of group messages with read, unread (undelivered), or delivered status, use queryGroupMessageReceiptMemberList instead.

queryGroupMessageReceiptMemberList usage example

Parameter description:

Code example:

// 1. Create query configuration
const config = new ZIMGroupMessageReceiptMemberListQueryConfig();
config.nextFlag = 0;    // Initially set to 0, then set to the nextFlag returned from the result
config.filterType = ZIMMessageReceiptFilterType.Read; // Default value, query read members

// 2. Call the API
zim.queryGroupMessageReceiptMemberList(message, groupID, 10, config)
    .then((result) => {
        // Query successful
        // result.userList  — List<ZIMGroupMemberInfo>, group member list matching the query conditions
        // result.nextFlag  — Start marker for the next query, 0 indicates query is complete
        // result.groupID   — Group ID
        // result.errorInfo — ZIMError, code 0 indicates success
    })
    .catch((error) => {
        // Query failed
    });

// 1. Create query configuration
const config = new ZIMGroupMessageReceiptMemberListQueryConfig();
config.nextFlag = 0;    // Initially set to 0, then set to the nextFlag returned from the result
config.filterType = ZIMMessageReceiptFilterType.Read; // Default value, query read members

// 2. Call the API
zim.queryGroupMessageReceiptMemberList(message, groupID, 10, config)
    .then((result) => {
        // Query successful
        // result.userList  — List<ZIMGroupMemberInfo>, group member list matching the query conditions
        // result.nextFlag  — Start marker for the next query, 0 indicates query is complete
        // result.groupID   — Group ID
        // result.errorInfo — ZIMError, code 0 indicates success
    })
    .catch((error) => {
        // Query failed
    });

Upgrade Guide for 3.0.0

Removed interfaces

ZIM initialization interface (create)

The deprecated legacy create(appID: number) interface has been removed. Please use the create interface that accepts a ZIMAppConfig parameter instead.

const appConfig: ZIMAppConfig = {
    appID: 12345678,
    appSign: 'appSign',
};
ZIM.create(appConfig);

const appConfig: ZIMAppConfig = {
    appID: 12345678,
    appSign: 'appSign',
};
ZIM.create(appConfig);

ZIM login interface (login)

The deprecated legacy login(userInfo: ZIMUserInfo, token: string) interface has been removed. Please use the login interface that accepts userID and a ZIMLoginConfig parameter instead.

const loginConfig: ZIMLoginConfig = {
    userName: 'userName',
    token: '', // If using Token authentication, fill in the Token
    isOfflineLogin: false,
};
await zim.login('userID', loginConfig);

const loginConfig: ZIMLoginConfig = {
    userName: 'userName',
    token: '', // If using Token authentication, fill in the Token
    isOfflineLogin: false,
};
await zim.login('userID', loginConfig);

ZIM message receive callback interface

The receivePeerMessage, receiveRoomMessage, and receiveGroupMessage events deprecated in 2.18.0 have been formally removed in this version. Migrate to messageReceived.

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // Handle messages of different conversation types based on conversationType
});

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // Handle messages of different conversation types based on conversationType
});

ZIM call invitation callback interface

The legacy callInvitationRejected, callInvitationAccepted, and callInviteesAnsweredTimeout events have been removed. Please use the callUserStateChanged event instead. The callback parameters of the callInvitationTimeout event have also been updated with an additional ZIMCallInvitationTimeoutInfo parameter.

zim.on('callUserStateChanged', (zim: ZIM, result: ZIMCallUserStateChangedEventResult) => {
    const { callUserList, callID } = result;
    // callUserList contains the list of users whose state has changed
    // Accept, reject, and timeout state changes can be handled uniformly
});

zim.on('callUserStateChanged', (zim: ZIM, result: ZIMCallUserStateChangedEventResult) => {
    const { callUserList, callID } = result;
    // callUserList contains the list of users whose state has changed
    // Accept, reject, and timeout state changes can be handled uniformly
});

importLocalMessages / exportLocalMessages interface removal

The importLocalMessages and exportLocalMessages interfaces have been temporarily removed in 3.0.0 with no replacement yet. This feature will be re-introduced in a later version. Please follow the SDK release notes for updates.

Newly deprecated interfaces (recommended migration)

ZIM message receive callback interface

The peerMessageReceived, roomMessageReceived, and groupMessageReceived events have been marked as deprecated in this version. They still work, but we recommend migrating to messageReceived as soon as possible.

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // Handle messages of different conversation types based on conversationType
});

zim.on('messageReceived', (zim: ZIM, result: ZIMMessageReceivedEventResult) => {
    const { messageList, info, conversationID, conversationType } = result;
    // Handle messages of different conversation types based on conversationType
});

ZIMGroupConversation deprecation

ZIMGroupConversation has been deprecated in 3.0.0. The isDisabled and mutedExpiredTime fields should be replaced with the corresponding properties of the base class ZIMConversation:

const isDisabled: boolean = conversation.isConversationDisabled;
const mutedExpiredTime: number = conversation.selfMutedExpiredTime;

const isDisabled: boolean = conversation.isConversationDisabled;
const mutedExpiredTime: number = conversation.selfMutedExpiredTime;

Field changes

ZIMConversationChangeInfo field change

The event property (of type ZIMConversationEvent) in ZIMConversationChangeInfo has been removed. Please use the action property (of type ZIMConversationChangeAction) in the same structure instead.

zim.on('conversationChanged', (zim: ZIM, result: ZIMConversationChangedEventResult) => {
    result.infoList.forEach(changeInfo => {
        const action: ZIMConversationChangeAction = changeInfo.action;
        // Handle conversation changes based on action
    });
});

zim.on('conversationChanged', (zim: ZIM, result: ZIMConversationChangedEventResult) => {
    result.infoList.forEach(changeInfo => {
        const action: ZIMConversationChangeAction = changeInfo.action;
        // Handle conversation changes based on action
    });
});

TypeScript interface rename

All TypeScript interfaces prefixed with ZIMEventOf in ZIMEventHandler.ts have been renamed according to a unified convention:

Naming rule: ZIMEventOf<Name>Result → ZIM<Name>EventResult

Typical examples:

Enum value rename

ZIMGroupMessageNotificationStatus

ZIMGroupMessageNotificationStatus.Disturb has been renamed to ZIMGroupMessageNotificationStatus.DoNotDisturb. Please check and replace all references in your code.

const status = ZIMGroupMessageNotificationStatus.DoNotDisturb;

const status = ZIMGroupMessageNotificationStatus.DoNotDisturb;

Upgrade Guide for 2.28.0

Changes to Event Callback Timing

Upgrade Guide for 2.21.0

Handling Room Reconnection

If the SDK reconnects WebSocket due to background switch or network issues, it will not automatically rejoin rooms that have already been joined. Developers need to listen to both connectionStateChanged and roomStateChanged events and actively call enterRoom or joinRoom to rejoin rooms.

For detailed handling, refer to: ZIM Room Disconnection Handling.

Upgrade Guide for 2.19.0

sendMediaMessage

Since version 2.19.0, you must use the sendMessage interface to send media messages. The sendMediaMessage interface is deprecated to unify message sending and facilitate future expansion.

In ZIMMessageSendNotification, the message parameter type of the onMediaUploadingProgress callback has changed from ZIMMessage to ZIMMediaMessage, ensuring only media messages trigger this callback. Typescript developers should fix their code according to IDE compilation errors. (Currently, only projects using Typescript and the replyMessage interface may be affected and need to resolve compilation errors.)

const imageMessage: ZIMMessage = {
    type: 11,
    fileLocalPath: File
}

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Developers can listen to this callback for actions before the message is sent
    },
// !mark
    onMessageUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => {
        // Media upload progress
    }
}

// !mark
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Message sent result
    })
    .catch((errorInfo) => {
        // Message send failed
    })

const imageMessage: ZIMMessage = {
    type: 11,
    fileLocalPath: File
}

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Developers can listen to this callback for actions before the message is sent
    },
// !mark
    onMessageUploadingProgress: (message: ZIMMediaMessage, currentFileSize: number, totalFileSize: number) => {
        // Media upload progress
    }
}

// !mark
zim.sendMessage(imageMessage, "TO_CONVERSATION_ID", 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Message sent result
    })
    .catch((errorInfo) => {
        // Message send failed
    })

Upgrade Guide for 2.18.0

Peer-to-Peer Message Receiving Callback

The original peer message receiving callback receivePeerMessage is deprecated. Please use peerMessageReceived instead.

The new callback supports the following:

• When the user is online, you can receive online peer messages via this callback.
• After re-logging into the ZIM SDK, you can receive all peer messages sent during offline periods (up to 7 days).

// New Interface
peerMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receivePeerMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

// New Interface
peerMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receivePeerMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

Room Message Receiving Callback

The original room message receiving callback receiveRoomMessage is deprecated. Please use roomMessageReceived instead.

The new callback supports the following:

• When the user is online, you can receive room messages in real-time.
• When the user recovers from offline to online and is still in the room, lost room messages during the offline period will be received via this callback.

// New Interface
roomMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveRoomMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

// New Interface
roomMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveRoomMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

Group Message Receiving Callback

The original group message receiving callback receiveGroupMessage is deprecated. Please use groupMessageReceived instead.

The new callback supports the following:

• When the user is online, you can receive online group messages via this callback.
• After re-logging into the ZIM SDK, you can receive all group messages sent during offline periods (up to 7 days).

// New Interface
groupMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveGroupMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

// New Interface
groupMessageReceived: (zim: ZIM, data: ZIMEventOfConversationMessageReceivedResult) => void;

// Old Interface
receiveGroupMessage: (zim: ZIM, data: ZIMEventOfReceiveConversationMessageResult) => void;

Upgrade Guide for 2.16.0

callCancel

In the new callCancel version, if the userIDs parameter contains one or more userIDs, the interface will only cancel invitations sent to these specific users. If the userIDs parameter is empty, all pending invitations will be cancelled.

In older versions, the callCancel interface cancels invitations for all invitees regardless of whether the userIDs parameter is given or empty.

Since the old ZIM SDK does not support single invitation cancellation, if you need to keep both the cancellation logic of older versions and the single cancellation capability of the new version, please isolate the call feature between old and new ZIM versions.

// Cancel invitations to userIdA and userIdB specifically
const callID = 'xxxx';
const invitees = ['userIdA','userIdB'];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })

// Cancel the entire call invitation; succeeds only if all invitees have not accepted
const callID = 'xxxx';
const invitees = [];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })

// Cancel invitations to userIdA and userIdB specifically
const callID = 'xxxx';
const invitees = ['userIdA','userIdB'];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })

// Cancel the entire call invitation; succeeds only if all invitees have not accepted
const callID = 'xxxx';
const invitees = [];  // Invitee userID list
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Operation successful
    })
    .catch((err: ZIMError) => {
        // Operation failed
    })