Receive messages

When new messages arrive in a conversation, the SDK dispatches the corresponding MessageItem in real time via message events across three primary scenarios:

• OnRecvNewMessage: Standard incoming messages received while connected online (applies to both one-to-one and group chats).
• OnRecvOfflineNewMessage: Historical offline messages retrieved in batches upon reconnecting to the server.
• OnRecvOnlineOnlyMessage: Ephemeral instant messages flagged for online-only delivery by the sender or server (these messages are not persisted to offline history).

const handleNewMessage = (message: MessageItem) => {
  // Identify the target conversation and deduplicate by message.clientMsgID
};

const handleOfflineNewMessage = (message: MessageItem) => {
  // Batch process offline messages, deduplicating by message.clientMsgID
};

const handleOnlineOnlyMessage = (message: MessageItem) => {
  // Handle transient online notifications or typing signals
};

// Register listeners
OpenIMSDK.on(OpenIMEvent.OnRecvNewMessage, handleNewMessage);
OpenIMSDK.on(OpenIMEvent.OnRecvOfflineNewMessage, handleOfflineNewMessage);
OpenIMSDK.on(OpenIMEvent.OnRecvOnlineOnlyMessage, handleOnlineOnlyMessage);

// Unregister listeners on cleanup
OpenIMSDK.off(OpenIMEvent.OnRecvNewMessage, handleNewMessage);
OpenIMSDK.off(OpenIMEvent.OnRecvOfflineNewMessage, handleOfflineNewMessage);
OpenIMSDK.off(OpenIMEvent.OnRecvOnlineOnlyMessage, handleOnlineOnlyMessage);

Client state reconciliation

When receiving incoming messages:

1. Identify the target conversation context (e.g. from the active chat view or session metadata).
2. Deduplicate and merge messages into your local message cache using clientMsgID as the primary key to prevent duplicate entries caused by network retries or multi-device synchronization.
3. Always unregister event listeners using identical function references when unmounting chat components, logging out, or switching accounts.