ZIM Upgrade Guide

This document provides notes and important information for upgrading the ZIM React Native SDK.

Upgrade Guide for 2.19.0

downloadMediaFile and Related Callbacks

The old downloadMediaFile API is deprecated. Please use the new downloadMediaFile API with the same name instead. The new version of downloadMediaFile adds a config parameter, which can be used to specify downloading a specific media item in a composite message.

In ZIMMediaDownloadingProgress and ZIMMediaDownloadedResult, the message parameter's type has changed from ZIMMediaMessage to ZIMMessage to support composite messages. TypeScript developers should adjust their code according to IDE compilation error hints.

// Suppose multipleMessage.messageInfoList[0] is a text message, multipleMessage.messageInfoList[1] is an image message
const multipleMessage: ZIMMessage = {
    type: 10,
    messageInfoList: [
        { type: 1, message: "Hello, World!" },
        { type: 11, fileLocalPath: '' }
    ]
}

const config: ZIMMediaDownloadConfig = {
    // Download the image message
    messageInfoIndex: 1
}
// !mark(1:4)

zim.downloadMediaFile(multipleMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // Download progress
    // Developers need to check message type and convert to the corresponding message type
    if (message.type === 10) {
// !mark
        const multipleMessage: ZIMMultipleMessage = message as ZIMMultipleMessage
        // Handle composite message
    }
    // Handle other message types
    ......

}).then((res: ZIMMediaDownloadedResult) => {
    // Download completed
    // Developers need to check message type and convert to the corresponding message type
    if (res.message.type === 10) {
// !mark
        const multipleMessage = res.message as ZIMMultipleMessage
        // Handle composite message
    }
    // Handle other message types
    ......
}).catch((errorInfo) => {
    // Download failed
})

// Suppose multipleMessage.messageInfoList[0] is a text message, multipleMessage.messageInfoList[1] is an image message
const multipleMessage: ZIMMessage = {
    type: 10,
    messageInfoList: [
        { type: 1, message: "Hello, World!" },
        { type: 11, fileLocalPath: '' }
    ]
}

const config: ZIMMediaDownloadConfig = {
    // Download the image message
    messageInfoIndex: 1
}
// !mark(1:4)

zim.downloadMediaFile(multipleMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // Download progress
    // Developers need to check message type and convert to the corresponding message type
    if (message.type === 10) {
// !mark
        const multipleMessage: ZIMMultipleMessage = message as ZIMMultipleMessage
        // Handle composite message
    }
    // Handle other message types
    ......

}).then((res: ZIMMediaDownloadedResult) => {
    // Download completed
    // Developers need to check message type and convert to the corresponding message type
    if (res.message.type === 10) {
// !mark
        const multipleMessage = res.message as ZIMMultipleMessage
        // Handle composite message
    }
    // Handle other message types
    ......
}).catch((errorInfo) => {
    // Download failed
})

sendMessage and Related Callbacks

Since version 2.19.0, sending media messages should use the sendMessage API. The sendMediaMessage API is deprecated to unify message sending and facilitate future extensibility.

In ZIMMessageSendNotification, the onMediaUploadingProgress callback’s message parameter type has changed from ZIMMessage to ZIMMediaMessage. This ensures only media messages trigger the progress callback. TypeScript developers should adjust their code as per IDE compilation error prompts. (Currently, only developers using TypeScript and the replyMessage API will encounter related compile errors.)

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

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Callback where developers can perform business logic 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 sending failed
    })

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

const config: ZIMMessageSendConfig = {
    priority: 1
}

// !mark
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Callback where developers can perform business logic 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 sending failed
    })

Upgrade Guide for 2.18.0

Peer Message Receive Callback

The original single chat message receive callback receivePeerMessage is deprecated. Please use peerMessageReceived instead.

The new callback supports:

• Receiving online peer-to-peer messages while the user is online.
• After the user re-logs in to ZIM SDK, receiving all offline peer messages sent within the last 7 days.

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

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

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

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

Room Message Receive Callback

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

The new callback supports:

• Receiving online room messages while the user is online.
• Once back online, if the user is still in the room, receiving all offline room messages sent while offline.

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

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

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

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

Group Message Receive Callback

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

The new callback supports:

• Receiving online group messages while the user is online.
• After the user re-logs in to ZIM SDK, receiving all offline group messages sent within the past 7 days.

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

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

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

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

Upgrade Guide for 2.16.0

callCancel

In the new callCancel API, if the userIDs parameter contains a userID, the API will cancel the invitation for that specific callee only. If the userIDs parameter is empty, the API will cancel invitations for all callees.

In contrast, the old version of callCancel, regardless of whether userIDs is empty or not, would cancel invitations for all callees.

Since the old ZIM SDK does not support cancellation for individual callees, if you need to keep the old cancellation logic and also use the new single-cancel feature, please isolate call logic between old and new ZIM versions.

// Cancel invitations for userIdA and userIdB only
const callID = 'xxxx';
const invitees = ['userIdA', 'userIdB'];  // List of invitee userIDs
const config: ZIMCallCancelConfig  = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Success
    })
    .catch((err: ZIMError) => {
        // Failure
    })

// Cancel the entire call invitation; works only if none of the callees have accepted
const callID = 'xxxx';
const invitees = [];  // List of invitee userIDs
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Success
    })
    .catch((err: ZIMError) => {
        // Failure
    })

// Cancel invitations for userIdA and userIdB only
const callID = 'xxxx';
const invitees = ['userIdA', 'userIdB'];  // List of invitee userIDs
const config: ZIMCallCancelConfig  = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Success
    })
    .catch((err: ZIMError) => {
        // Failure
    })

// Cancel the entire call invitation; works only if none of the callees have accepted
const callID = 'xxxx';
const invitees = [];  // List of invitee userIDs
const config: ZIMCallCancelConfig = { extendedData: 'xxxx' }; 
zim.callCancel(invitees, callID, config)
    .then((res: ZIMCallCancelSentResult) => {
        // Success
    })
    .catch((err: ZIMError) => {
        // Failure
    })

Upgrade Guide for 3.0.0

Removed deprecated APIs

ZIM initialization API (create)

The deprecated create(appID: number) API has been removed. Please use the create API that accepts ZIMAppConfig instead.

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

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

ZIM login API (login)

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

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

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

ZIM message sending API (sendMessage)

The deprecated sendPeerMessage, sendRoomMessage, sendGroupMessage, and sendMediaMessage APIs have been removed. Please use the sendMessage API with the notification parameter instead.

const textMessage: ZIMTextMessage = {
    type: 1,
    message: 'Hello',
};
const config: ZIMMessageSendConfig = {
    priority: 1,
};
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Business logic before message is sent
    },
};
zim.sendMessage(textMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Message sent result
    })
    .catch((errorInfo) => {
        // Message sent failed
    });

const textMessage: ZIMTextMessage = {
    type: 1,
    message: 'Hello',
};
const config: ZIMMessageSendConfig = {
    priority: 1,
};
const notification: ZIMMessageSendNotification = {
    onMessageAttached: (message: ZIMMessage) => {
        // Business logic before message is sent
    },
};
zim.sendMessage(textMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Message sent result
    })
    .catch((errorInfo) => {
        // Message sent failed
    });

ZIM media file download API (downloadMediaFile)

The deprecated downloadMediaFile API (without config parameter) has been removed. Please use the new downloadMediaFile API with the ZIMMediaDownloadConfig parameter instead.

const config: ZIMMediaDownloadConfig = {};
zim.downloadMediaFile(imageMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // Download progress
}).then((res: ZIMMediaDownloadedResult) => {
    // Download complete
}).catch((errorInfo) => {
    // Download failed
});

const config: ZIMMediaDownloadConfig = {};
zim.downloadMediaFile(imageMessage, 1, config, (message: ZIMMessage, currentFileSize: number, totalFileSize: number) => {
    // Download progress
}).then((res: ZIMMediaDownloadedResult) => {
    // Download complete
}).catch((errorInfo) => {
    // Download failed
});

ZIM message receive callback API

The receivePeerMessage, receiveRoomMessage, and receiveGroupMessage events deprecated in 2.18.0 have been officially removed in this version. It is recommended to migrate to messageReceived.

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

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

ZIM call invitation callback APIs

The old 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, adding a ZIMCallInvitationTimeoutInfo parameter.

zim.on('callUserStateChanged', (zim: ZIM, result: ZIMCallUserStateChangedEventResult) => {
    const { callUserList, callID } = result;
    // callUserList contains the list of users whose status changed
    // You can uniformly handle accept, reject, timeout, and other status changes
});

zim.on('callUserStateChanged', (zim: ZIM, result: ZIMCallUserStateChangedEventResult) => {
    const { callUserList, callID } = result;
    // callUserList contains the list of users whose status changed
    // You can uniformly handle accept, reject, timeout, and other status changes
});

importLocalMessages / exportLocalMessages APIs removed

The importLocalMessages and exportLocalMessages APIs have been temporarily removed in version 3.0.0, and there is no replacement API at this time. This functionality will be re-enabled in future versions. Please follow the SDK release notes for updates.

Newly deprecated APIs (recommended to migrate)

ZIM message receive callback APIs

The peerMessageReceived, roomMessageReceived, and groupMessageReceived events have been marked as deprecated in this version. They can still be used normally at present, but it is recommended to migrate to messageReceived as soon as possible.

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

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

ZIMGroupConversation deprecated

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;

Enum value removals

ZIMMessageType enum value removed

ZIMMessageType.System (value 30) has been removed from the ZIMMessageType enum, and the ZIMSystemMessage type has also been removed. If you need to send system-level commands, please use ZIMCommandMessage instead.

// Use ZIMCommandMessage instead of ZIMSystemMessage
const commandMessage: ZIMCommandMessage = {
    type: 2,
    message: new Uint8Array([/* payload bytes */]),
};
zim.sendMessage(commandMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Send result
    });

// Use ZIMCommandMessage instead of ZIMSystemMessage
const commandMessage: ZIMCommandMessage = {
    type: 2,
    message: new Uint8Array([/* payload bytes */]),
};
zim.sendMessage(commandMessage, 'toConversationID', 0, config, notification)
    .then((res: ZIMMessageSentResult) => {
        // Send result
    });

ZIMCallUserState enum value removed

ZIMCallUserState.Offline (value 4) has been removed from the ZIMCallUserState enum. Please check your code for any references to this enum value and remove them.

// The following enum value has been removed, please check and remove references to this value in your code
// ZIMCallUserState.Offline  (value 4)

// The following enum value has been removed, please check and remove references to this value in your code
// ZIMCallUserState.Offline  (value 4)

Field changes

ZIMUserFullInfo.userAvatarUrl deprecated

ZIMUserFullInfo.userAvatarUrl has been deprecated. Please use ZIMUserFullInfo.baseInfo.userAvatarUrl instead.

const avatarUrl: string = userFullInfo.baseInfo.userAvatarUrl;

const avatarUrl: string = userFullInfo.baseInfo.userAvatarUrl;

ZIMMessage.conversationSeq replaced with messageSeq

ZIMMessage.conversationSeq has been removed. Please use ZIMMessage.messageSeq instead.

const seq: number = message.messageSeq;

const seq: number = message.messageSeq;

ZIMMessageDeletedInfo.isDeleteConversationAllMessage removed

ZIMMessageDeletedInfo.isDeleteConversationAllMessage has been removed. Please use ZIMMessageDeletedInfo.messageDeleteType instead.

const deleteType: ZIMMessageDeleteType = deletedInfo.messageDeleteType;
// Determine whether it is a single deletion or a full deletion through deleteType

const deleteType: ZIMMessageDeleteType = deletedInfo.messageDeleteType;
// Determine whether it is a single deletion or a full deletion through deleteType

ZIMGroupMemberInfo.memberAvatarUrl removed

ZIMGroupMemberInfo.memberAvatarUrl has been removed. Please use ZIMGroupMemberInfo.userAvatarUrl instead.

const avatarUrl: string = groupMemberInfo.userAvatarUrl;

const avatarUrl: string = groupMemberInfo.userAvatarUrl;

ZIMGroupOperatedInfo structure change

The ZIMGroupOperatedInfo.operatedUserInfo field has been removed. Its internal fields have been flattened into ZIMGroupOperatedInfo, and can be accessed directly from ZIMGroupOperatedInfo.

// Get fields directly from ZIMGroupOperatedInfo
const operatorUserID: string = groupOperatedInfo.userID;
const operatorUserName: string = groupOperatedInfo.userName;
const operatorAvatarUrl: string = groupOperatedInfo.userAvatarUrl;

// Get fields directly from ZIMGroupOperatedInfo
const operatorUserID: string = groupOperatedInfo.userID;
const operatorUserName: string = groupOperatedInfo.userName;
const operatorAvatarUrl: string = groupOperatedInfo.userAvatarUrl;

ZIMCallInvitationSentInfo.errorInvitees replaced

ZIMCallInvitationSentInfo.errorInvitees has been removed. Please use ZIMCallInvitationSentInfo.errorUserList instead. The type has changed from ZIMCallUserInfo[] to ZIMErrorUserInfo[].

zim.callInvite(invitees, config)
    .then((res: ZIMCallInvitationSentResult) => {
        for (const errorUser of res.errorUserList) {
            // errorUser.userID, errorUser.reason
        }
    });

zim.callInvite(invitees, config)
    .then((res: ZIMCallInvitationSentResult) => {
        for (const errorUser of res.errorUserList) {
            // errorUser.userID, errorUser.reason
        }
    });

ZIMConversationChangeInfo field change

The event property (type ZIMConversationEvent) in ZIMConversationChangeInfo has been removed. Please use the action property (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
    });
});

Type interface name changes

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

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

Typical examples:

Enum value renames

ZIMGroupMessageNotificationStatus

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

const status = ZIMGroupMessageNotificationStatus.DoNotDisturb;

const status = ZIMGroupMessageNotificationStatus.DoNotDisturb;

setRoomMembersAttributes behavior change

Starting from version 3.0.0, when setting room member attributes via setRoomMembersAttributes, if isDeleteAfterOwnerLeft is false, the room member attributes will not be deleted when the user leaves the room. In versions 2.x.x, attributes were first deleted when the user left the room and then restored when the user returned.