Skip to main content

Event Listening

Adding Listeners​

You can use the [addEventListener] method to listen for various event notifications triggered internally by IMLib. Multiple listener functions can be bound to the same event type, and they will all be executed sequentially.

If you only want to listen for an event once, you can use [onceEventListener].

// Message listener
const Events = RongIMLib.Events;

RongIMLib.addEventListener(Events.MESSAGES, (evt) => {
  console.log(evt.messages);
})
:::warning[Common Issue: Receiving duplicate data in listeners]
This is usually caused by duplicate registration of the same listener at the business layer. Common scenarios include registering listeners in a component's lifecycle, where each component creation triggers a new registration, ultimately resulting in duplicate data reception.

Recommended practices:


- Global registration: It's recommended to register listeners at the application entry point or a centralized management location to ensure single registration.


- Component registration requires synchronous cleanup: If listeners must be registered within components, be sure to remove them when the component is destroyed to prevent memory leaks and duplicate callbacks.

:::


## Removing Listeners

To avoid memory leaks, it's recommended to promptly remove event listeners when they are no longer needed using removeEventListener or removeEventListeners.


- `removeEventListener`: Removes a specific listener function for a given event.


- `removeEventListeners`: Removes all listener functions for a given event.

```js
const Events = RongIMLib.Events

const listener = (evt) => console.log(evt.messages)

// Add specific event listener
RongIMLib.addEventListener(Events.MESSAGES, listener)

// Remove specific event listener
RongIMLib.removeEventListener(Events.MESSAGES, listener)

// Remove all listeners for a specific event
RongIMLib.removeEventListeners(Events.MESSAGES)


## Event Descriptions

The following table lists all event types currently supported by IMLib, along with their return data types and descriptions. You can flexibly add corresponding event listeners based on business requirements.

| Event Name                     | Callback Data Type   | Description                 | Version |
| :---------------------------- | :----- | :----------------------- | :----------------------- |
| CONNECTING                    | void    | Connection in progress                  | - |
| CONNECTED                     | void    | Connection established successfully                   | - |
| DISCONNECT                    | [ErrorCode]     | Connection disconnected  **Note**: Starting from version 5.7.0, the callback parameter type changed from [ConnectionStatus] to [ErrorCode]               | |
| SUSPEND                       | [ErrorCode]     | Connection abnormally disconnected (auto-reconnect) **Note**: Starting from version 5.7.0, the callback parameter type changed from [ConnectionStatus] & [ErrorCode] to [ErrorCode]   | |
| MESSAGES                      | [IMessagesEvent]    | Message received                 | |
| READ_RECEIPT_RECEIVED         | [IReadReceiptReceivedEvent]    | Read receipt received (one-to-one chat)     | |
| MESSAGE_RECEIPT_REQUEST       | [IMessageReceiptRequestEvent]    | Read receipt request received (group chat) | |
| MESSAGE_RECEIPT_RESPONSE      | [IMessageReceiptResponseEvent]   | Read receipt response received (group chat) | |
| CONVERSATION                  | [IConversationEvent]    | Conversation change notification         | | <!--public-cloud-only start-->
| CHATROOM                      | [IChatroomListenerData]   | Chatroom change notification. **Note**: To listen for chatroom member changes, submit a ticket to enable the service.       | | <!--public-cloud-only end-->
| EXPANSION                     | [IExpansionListenerData]    | Extension change notification         | |
| PULL_OFFLINE_MESSAGE_FINISHED | void    | Offline message pull completed         | |
| TAG                           | void    | (For multi-device login scenarios) Tag list notification, indicating the user may have created, removed, or edited a tag on another device. Upon receiving this notification, actively call `getTags` to retrieve all tags for UI updates. This tag list contains all tags used for marking conversations.        | |
| CONVERSATION_TAG              | void    | (For multi-device login scenarios) Conversation tag change notification, indicating the user may have modified tags on a conversation from another device. Upon receiving this notification, based on the locally rendered conversation list, actively call `getTagsFromConversation` to retrieve all tags for each conversation to update UI rendering.    | |
| TYPING_STATUS                 | [ITypingStatusEvent]   | Typing status notification     | |
| MESSAGE_BLOCKED               | [IBlockedMessageInfo]  | Sensitive word callback notification. <!--public-cloud-only start-->Requires submitting a ticket to enable the service. Disabled by default.<!--public-cloud-only end-->    | 5.0.2 | <!--public-cloud-only start-->
| ULTRA_GROUP_ENABLE            | void | Ultra group conversation list synchronization completed, ultra group APIs can be called;<br/>Starting from version 5.20, no callback data is provided | 5.2.0 |
| OPERATE_STATUS                | [IOperateStatusNotify]  | Ultra group input status notification | 5.2.0 |
| ULTRA_GROUP_MESSAGE_EXPANSION_UPDATED | [IAReceivedMessage]   | Ultra group message extension update notification | 5.2.0 |
| ULTRA_GROUP_MESSAGE_MODIFIED  | [IAReceivedMessage]  | Ultra group message modified notification | 5.2.0 |
| ULTRA_GROUP_MESSAGE_RECALLED  | [IAReceivedMessage]   | Ultra group message recalled notification | 5.2.0 |
| ULTRA_GROUP_CHANNEL_TYPE_CHANGE  | [IUltraChannelChangeInfo]    | Ultra group channel type changed | 5.4.2 |
| ULTRA_GROUP_CHANNEL_DELETE  | [IUltraChannelDeleteInfo]  | Ultra group channel deleted | 5.4.2 |
| ULTRA_GROUP_CHANNEL_USER_KICKED  | [IUltraChannelUserKickedInfo]    | Ultra group private channel member removed | 5.4.2 |
| DATABASE_UPGRADE_WILL_START  | void    | Database upgrade starting, Electron only | 5.10.4 |
| DATABASE_UPGRADING  | number    | Database upgrading, Electron only | 5.10.4 |
| DATABASE_UPGRADE_DID_COMPLETE  | [ErrorCode]    | Database upgrade completed, Electron only | 5.10.4 |
| GROUP_OPERATION  | [IGroupOperationInfo]    | Group operation callback, operation type can be determined by `operation` in `IGroupOperationInfo` | 5.12.0 |
| GROUP_INFO_CHANGED  | [IGroupInfoChanged]    | Group information change notification | 5.12.0 |
| GROUP_MEMBER_INFO_CHANGED  | [IGroupMemberInfoChanged]    | Group member information change notification | 5.12.0 |
| GROUP_APPLICATION_EVENT  | [IGroupApplicationInfo]    | User application or invitation event and result notification | 5.12.0 |
| GROUP_REMARK_CHANGED_SYNC  | [IGroupRemarkChangedSync]    | Group name alias update multi-device sync notification | 5.12.0 |
| GROUP_FOLLOWS_CHANGED_SYNC  | [IGroupFollowsChangedSync]    | Group member special follow multi-device sync notification | 5.12.0 |
| FRIEND_ADDED  | [IFriendAdd]    | Friend added notification | 5.12.0 |
| FRIEND_DELETE  | [IFriendDelete]    | Friend removed notification | 5.12.0 |
| FRIEND_APPLICATION_STATUS_CHANGED  | [IFriendApplicationStatusChange]    | Friend request notification | 5.12.0 |
| FRIEND_CLEARED  | number    | Clear all friends notification, triggered by Server API call to clear all friends | 5.12.0 |
| FRIEND_INFO_CHANGED_SYNC  | [IFriendInfoChangedSync]    | Multi-device sync friend information change notification | 5.12.0 |
| CONVERSATIONS_SYNCED  | void | One-to-one and group chat conversation list sync completed | 5.20.0 |
| MESSAGE_MODIFIED | - | Message modified notification | 5.26.0 |
| MESSAGE_MODIFIED_SYNC_COMPLETED | - | One-to-one and group chat message edit sync completed notification, triggered only during initial sync after successful connection | 5.26.0 |
| DATABASE_OPENED | - | Database opened notification, Electron platform only | 5.28 |

<!-- api links -->
[addEventListener]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#addEventListener
[onceEventListener]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#onceEventListener
[removeEventListener]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#removeEventListener
[removeEventListeners]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/modules.html#removeEventListeners
[ConnectionStatus]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/enums/ConnectionStatus.html
[ErrorCode]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/enums/ErrorCode.html
[IMessagesEvent]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IMessagesEvent.html
[IReadReceiptReceivedEvent]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IReadReceiptReceivedEvent.html
[IMessageReceiptRequestEvent]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IMessageReceiptRequestEvent.html
[IMessageReceiptResponseEvent]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IMessageReceiptResponseEvent.html
[IConversationEvent]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IConversationEvent.html
[IChatroomListenerData]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IChatroomListenerData.html
[IExpansionListenerData]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IExpansionListenerData.html
[ITypingStatusEvent]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/ITypingStatusEvent.html
[IBlockedMessageInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IBlockedMessageInfo.html
[IAReceivedConversation]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IAReceivedConversation.html
[IOperateStatusNotify]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IOperateStatusNotify.html
[IAReceivedMessage]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IAReceivedMessage.html
[IUltraChannelChangeInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IUltraChannelChangeInfo.html
[IUltraChannelDeleteInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IUltraChannelDeleteInfo.html
[IUltraChannelUserKickedInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IUltraChannelUserKickedInfo.html
[IGroupOperationInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGroupOperationInfo.html
[IGroupInfoChanged]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGroupInfoChanged.html
[IGroupMemberInfoChanged]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGroupMemberInfoChanged.html
[IGroupApplicationInfo]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGroupApplicationInfo.html
[IGroupRemarkChangedSync]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGroupRemarkChangedSync.html
[IGroupFollowsChangedSync]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IGroupFollowsChangedSync.html
[IFriendAdd]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IFriendAdd.html
[IFriendDelete]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IFriendDelete.html
[IFriendApplicationStatusChange]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IFriendApplicationStatusChange.html
[IFriendInfoChangedSync]: https://doc.rongcloud.cn/apidoc/im-web/latest/zh_CN/interfaces/IFriendInfoChangedSync.html
Last updated on