Listen to Chatroom Events
The chatroom business provides three types of event delegation protocols for client apps: chatroom status delegation, chatroom member change delegation, and chatroom event notification.
Through the above delegation provided by the SDK, client apps can obtain information from the RC server about the destruction status of chatrooms, the status of users joining and leaving chatrooms on the current and other clients, notifications of members entering and exiting chatrooms, and information related to muting and banning members in chatrooms.
| Delegation Protocol | Name | Description |
|---|---|---|
| RCChatRoomStatusDelegate | Chatroom Status Delegation | Receives events of users joining and leaving chatrooms on the current client and information about chatroom destruction status. |
RCChatRoomMemberDelegate | Chatroom Member Change Delegation | Receives information about users joining and leaving the current chatroom. |
ChatRoomNotifyEventDelegate | Chatroom Event Notification Delegation | Receives information related to muting and banning members in the current chatroom; receives information about the current user joining and leaving chatrooms on other devices. |
Listen to Chatroom Status
To receive events of users joining and leaving chatrooms on the current client and information about chatroom destruction status from the RC server, you can add an RCChatRoomStatusDelegate delegate via the setChatRoomStatusDelegate or addChatRoomStatusDelegate method of RCChatRoomClient (or RCIMClient).
Chatroom Status Events
Below is a list of events and delegate methods provided by the chatroom status delegation protocol RCChatRoomStatusDelegate.
@protocol RCChatRoomStatusDelegate <NSObject>
/*!
Callback when starting to join a chatroom
- Parameter chatroomId: Chatroom ID
*/
- (void)onChatRoomJoining:(NSString *)chatroomId;
/*!
Callback when successfully joined a chatroom
- Parameter chatroomId: Chatroom ID
- Parameter response: Information returned upon successful joining
- Since: 5.6.3
*/
- (void)onChatRoomJoined:(NSString *)chatroomId response:(RCJoinChatRoomResponse *)response;
/*!
Callback when successfully joined a chatroom
- Parameter chatroomId: Chatroom ID
*/
- (void)onChatRoomJoined:(NSString *)chatroomId __deprecated_msg("Use [RCChatRoomStatusDelegate onChatRoomJoined:response:] instead");
/*!
Callback when failed to join a chatroom
- Parameter chatroomId: Chatroom ID
- Parameter errorCode: Error code for the failure
If the error code is KICKED_FROM_CHATROOM or RC_CHATROOM_NOT_EXIST, the chatroom will not be automatically rejoined. The app needs to handle it according to its own logic.
*/
- (void)onChatRoomJoinFailed:(NSString *)chatroomId errorCode:(RCErrorCode)errorCode;
/*!
Callback when the chatroom is reset after successfully joining. After receiving this callback, the onChatRoomJoined: callback will also be received.
- Parameter chatroomId: Chatroom ID
*/
- (void)onChatRoomReset:(NSString *)chatroomId;
/*!
Callback when successfully left a chatroom
- Parameter chatroomId: Chatroom ID
*/
- (void)onChatRoomQuited:(NSString *)chatroomId;
/*!
Callback when the chatroom is destroyed. This callback is only received when the user is online and the room is destroyed.
- Parameter chatroomId: Chatroom ID
- Parameter type: Reason for chatroom destruction
*/
- (void)onChatRoomDestroyed:(NSString *)chatroomId type:(RCChatRoomDestroyType)type;
@end
Set Chatroom Status Delegate
// Set IMLib's chatroom status listener
[[RCChatRoomClient sharedChatRoomClient] setChatRoomStatusDelegate:self];
Starting from version 5.2.5, the SDK supports adding multiple delegates. The method to add a delegate is as follows:
// Add IMLib's chatroom status listener @Since 5.2.5
[[RCChatRoomClient sharedChatRoomClient] addChatRoomStatusDelegate:self];
Remove Chatroom Status Delegate
Starting from version 5.2.5, the SDK supports adding multiple delegates. The method to remove a delegate is as follows:
// Remove IMLib's chatroom status listener @Since 5.2.5
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomStatusDelegate:self];
Listen to Chatroom Member Changes
Starting from version 5.1.4, the SDK supports listening to chatroom member changes.
The SDK provides the RCChatRoomMemberDelegate protocol in RCChatRoomClient, allowing the current client to listen to the joining and leaving behavior of other members in the chatroom.
Enable the Service
You can enable this feature in the RC Console by navigating to Configuration > Chat settings > Basic features > Chatroom > Chatroom Member Change Listener. After enabling, the system will send callback notifications to other members in the chatroom when a user joins or leaves, which will increase the message volume.
Set Chatroom Member Change Delegate
The following code example shows how to set the chatroom member change delegate. Starting from version 5.6.7, a new delegate method returning the RCChatRoomMemberActionModel object has been added, which includes the current number of members in the chatroom.
[RCChatRoomClient sharedChatRoomClient].memberDelegate = self;
#pragma mark - RCChatRoomMemberDelegate
- (void)memberDidChange:(NSArray<RCChatRoomMemberAction *> *)members inRoom:(NSString *)roomId {
// Handle the member change with the array of RCChatRoomMemberAction objects and the roomId
}
/**
- Since: 5.6.7
*/
- (void)memberDidChange:(RCChatRoomMemberActionModel *)actionModel {
// Handle the member change with the RCChatRoomMemberActionModel object
NSString *roomId = actionModel.roomId;
NSArray<RCChatRoomMemberAction *> *chatRoomMemberActions = actionModel.chatRoomMemberActions;
NSUInteger memberCount = actionModel.memberCount;
for (RCChatRoomMemberAction *action in chatRoomMemberActions) {
// Access the properties of RCChatRoomMemberAction object
NSString *memberId = action.memberId;
RCChatRoomMemberActionType actionType = action.action;
if (actionType == RCChatRoomMemberActionType_Join) {
NSLog(@"Action Type: Join");
} else if (actionType == RCChatRoomMemberActionType_Quit) {
NSLog(@"Action Type: Leave");
}
}
}
When other users join or leave the chatroom, the SDK will trigger both memberDidChange methods simultaneously, with callbacks on a child thread. The RCChatRoomMemberAction list contains information about members who have joined or left the chatroom. The RCChatRoomMemberActionModel additionally encapsulates the current number of members in the chatroom (referring to those who have joined but not left). It is recommended to use the delegate method that returns the RCChatRoomMemberActionModel object.
If the current user loses connection to the chatroom due to network issues, they will not be able to listen to the joining and leaving behavior of other members during the disconnection period.
Listen to Chatroom Event Notifications
Starting from version 5.4.5, the SDK supports listening to chatroom event notifications.
To receive information from the RC server about muting and banning members in the current chatroom, as well as information about the current user joining and leaving chatrooms on other devices, you can add a RCChatRoomNotifyEventDelegate delegate via the addChatRoomNotifyEventDelegate method of RCChatRoomClient.
| Delegate Method | Trigger Condition | Description |
|---|---|---|
| chatRoomNotifyMultiLoginSync:(RCChatRoomSyncEvent *)event; | When a user joins or leaves a chatroom on another client in a multi-device login scenario | Receives events of the user joining and leaving chatrooms on the current client |
| chatRoomNotifyBlock:(RCChatRoomMemberBlockEvent *)event; | When muting or unmuting related events occur in the chatroom the user is in | Whether to receive notifications depends on whether needNotify is set to true when calling the relevant server API for muting or unmuting. |
| chatRoomNotifyBan:(RCChatRoomMemberBanEvent *)event; | When banning or unbanning related events occur in the chatroom the user is in | Whether to receive notifications depends on whether needNotify is set to true when calling the relevant server API for banning or unbanning. |
Multi-Device Login Event Notification
When a user joins or leaves a chatroom on another client in a multi-device login scenario, the chatRoomNotifyMultiLoginSync:(RCChatRoomSyncEvent *)event method is triggered.
| Trigger Scenario | Notification Scope | Description |
|---|---|---|
| A user logs in on multiple devices and joins a chatroom on one device | The user who joined | When the current user joins a chatroom on one device, other online devices will receive notifications. Offline devices will not be notified. The returned data includes: chatroom ID, join time. |
| A user logs in on multiple devices and leaves a chatroom on one device | The user who left | When the current user leaves a chatroom on one device, other online devices will receive notifications. Offline devices will not be notified. The returned data includes: chatroom ID, leave time. |
| A user logs in on multiple devices and is already in a chatroom, joining a new chatroom causes them to be kicked out of the previous chatroom | The current user and all members of the kicked-out chatroom | If Allow a single user to join multiple chatrooms is enabled in the console, no notification will be sent. The returned data includes: chatroom ID, time of being kicked out. |
The RCChatRoomSyncEvent is defined as follows:
@interface RCChatRoomSyncEvent : NSObject
/*!
Chatroom ID
*/
@property (nonatomic, copy) NSString *chatroomId;
/**
Synchronization notification status
*/
@property (nonatomic, assign) RCChatRoomSyncStatus status;
/**
If status is 0, distinguishes the leave type:
1, left voluntarily,
2, kicked out due to multi-device join
*/
@property (nonatomic, assign) NSInteger reason;
/**
Synchronization notification time
Time when the user joined/left/was kicked out (in milliseconds)
*/
@property (nonatomic, assign) long long time;
/**
Additional information
*/
@property (nonatomic, copy, nullable) NSString *extra;
@end
Ban-Related Event Notification
When banning or unbanning events occur in the chatroom the user is in, and the relevant Server API is called with needNotify set to true, the chatRoomNotifyBlock:(RCChatRoomMemberBlockEvent *)event method is triggered.
| Trigger Scenario | Notification Scope | Description |
|---|---|---|
| Ban a Chatroom User | All members in the chatroom | The returned data includes: chatroom ID, list of banned user IDs, ban time and duration, additional information. |
| Unban a Chatroom User | The unbanned user | The returned data includes: chatroom ID, current user ID, additional information. |
The RCChatRoomMemberBlockEvent is defined as follows:
@interface RCChatRoomMemberBlockEvent : NSObject
/*!
Chatroom ID
*/
@property (nonatomic, copy) NSString *chatroomId;
/**
Ban type, 0 for unban, 1 for ban
*/
@property (nonatomic, assign) RCChatRoomMemberOperateType operateType;
/**
Total ban time, present when banning (in milliseconds), maximum value is 43200 minutes (1 month), minimum value is 1 minute
*/
@property (nonatomic, assign) NSInteger durationTime;
/**
Operation time (in milliseconds)
*/
@property (nonatomic, assign) long long operateTime;
/**
List of banned user IDs; for unban, it is the current user ID
*/
@property (nonatomic, copy) NSArray<NSString *> *userIdList;
/**
Additional information
*/
@property (nonatomic, copy, nullable) NSString *extra;
@end
Mute-Related Event Notification
When muting or unmuting events occur in the chatroom the user is in, and the relevant Server API is called with needNotify set to true, the chatRoomNotifyBan:(RCChatRoomMemberBanEvent *)event method is triggered.
| Trigger Scenario | Notification Scope | Description |
|---|---|---|
| Mute a Specific Chatroom User | All members in the chatroom | The returned data includes: chatroom ID, list of muted user IDs, mute time and duration, additional information. |
| Unmute a Specific Chatroom User | All members in the chatroom | The returned data includes: chatroom ID, list of unmuted user IDs, unmute time, additional information. |
| Set Chatroom-Wide Mute | All members in the chatroom | The returned data includes: chatroom ID, mute time, additional information. |
| Cancel Chatroom-Wide Mute | All members in the chatroom | The returned data includes: chatroom ID, unmute time, additional information. |
| Add to Chatroom-Wide Mute Allowlist | All members in the chatroom | The returned data includes: chatroom ID, list of users added to the allowlist, allowlist setting time, additional information. |
| Remove from Chatroom-Wide Mute Allowlist | All members in the chatroom | The returned data includes: chatroom ID, list of users removed from the allowlist, allowlist removal time, additional information. |
| Global Mute User | The globally muted user | The returned data includes: chatroom ID, mute time and duration, additional information. |
| [Cancel Global Mute User][doc-page-cancel-global-mute-user] | The globally unmuted user | The returned data includes: chatroom ID, unmute time, additional information. |
The RCChatRoomMemberBanEvent is defined as follows:
@interface RCChatRoomMemberBanEvent : NSObject
/*!
Chatroom ID
*/
@property (nonatomic, copy) NSString *chatroomId;
/**
Mute operation type, see enumeration values
Mute/Unmute operation types:
0: Unmute a specific user in the chatroom;
1: Mute a specific user in the chatroom;
2: Cancel chatroom-wide mute;
3: Chatroom-wide mute
4: Remove from mute allowlist
5: Add to mute allowlist
6: Cancel global mute for a user in the chatroom
7: Global mute for a user in the chatroom
*/
@property (nonatomic, assign) RCChatRoomMemberBanType banType;
/**
Total mute time (present for mute operations) (in milliseconds), maximum value is 43200 minutes (1 month), minimum value is 1 minute
*/
@property (nonatomic, assign) NSInteger durationTime;
/**
Operation time (in milliseconds)
*/
@property (nonatomic, assign) long long operateTime;
/**
List of muted/unmuted user IDs
*/
@property (nonatomic, copy) NSArray<NSString *> *userIdList;
/**
Additional information
*/
@property (nonatomic, copy, nullable) NSString *extra;
@end
Set Chatroom Event Notification Delegate
Starting from version 5.4.5, the SDK supports the RCChatRoomNotifyEventDelegate delegation protocol. The following code example shows how to set the chatroom event notification delegate.
[[RCChatRoomClient sharedChatRoomClient] addChatRoomNotifyEventDelegate:self];
Remove Chatroom Event Notification Delegate
Starting from version 5.4.5, the SDK supports the RCChatRoomNotifyEventDelegate delegation protocol. The following code example shows how to remove the chatroom event notification delegate.
[[RCChatRoomClient sharedChatRoomClient] removeChatRoomNotifyEventDelegate:self];