Chat Room
Update time: 2021/12/06 15:32:58
Overview
CommsEase provides the chat room feature. There is no upper limit for the number of users. Users can freely enter and exit a chat room. The creation and closure of a chat room need to be completed using the server-side API.
A chat room prototype:
@interface NIMChat room : NSObject
/**
* Chat room ID.
*/
@property (nullable,nonatomic,copy) NSString *roomId;
/**
* Chat room name.
*/
@property (nullable,nonatomic,copy) NSString *name;
/**
* The announcement.
*/
@property (nullable,nonatomic,copy) NSString *announcement;
/**
* The creator.
*/
@property (nullable,nonatomic,copy) NSString *creator;
/**
* The third-party extension field is up to 4K in length.
*/
@property (nullable,nonatomic,copy) NSString *ext;
/**
* Number of current online users.
*/
@property (nonatomic,assign) NSInteger onlineUserCount;
/**
* Live streaming address. To meet the needs of live streaming, set the push and pull URL.
*/
@property (nullable,nonatomic,copy) NSString *broadcastUrl;
/**
* Permission levels for updating a chat room queue.
*/
@property (nonatomic,assign) NIMChat roomQueueModificationLevel queueModificationLevel;
/**
* Specify whether to mute all members in a chat room. If all members are muted, only the administrator can send messages.
*/
- (BOOL)inAllMuteMode;
@end
Enter a chat room
Users must call The API to enter a chat room before sending and receiving messages in a chat room. Users can only enter a chat room by a manual login. Inviting a user to a chat room is not allowed. Users can enter up to 10 chat rooms at the same time.
Users can enter a chat room by independent mode or non-independent mode.
-
The independent mode is how to enter a chat room when a user does not log in to IM app. The mode applies to scenarios that only need the chat room feature.
-
The non-independent mode is how to enter a chat room after a user logs in to IM app. The mode applies to the scenarios that only need IM and the chat room feature.
-
Set the authentication method of a chat room by the parameter
NIMChat roomIndependentMode
of the method for entering the chat room. By default, the non-independent mode is set.
@protocol NIMChat roomManager <NSObject>
/**
* Enter a chat room
*
* @param request - Request for entering a chat room
* @param completion - The callback that the user has entered a chat room.
*/
- (void)enterChat room:(NIMChat roomEnterRequest *)request
completion:(NIMChat roomEnterHandler)completion;
@end
NIMChatroomEnterRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID. |
roomNickname | NSString | Chat room nickname. |
roomAvatar | NSString | The photo profile of a chat room. The upper-level layer can set the photo profile in the chat room as required. If the photo profile is not set, use the user profile information. |
roomExt | NSString | My chat room member information extension field, which is only valid for the current entry. |
roomNotifyExt | NSString | The extension field of a chat room event notification |
retryCount | NSInteger | The number of chat room reconnection, which is set to 3 by default. When it is set to 0, the SDK will not retry once a connection fails. The app can set it as required. |
mode | NIMChat roomIndependentMode | The independent mode of a chat room, which is nil by default. |
-
Set the parameter when entering a chat room. The extension
roomExt
will be included in every message. This field can be included in users' custom information in a chat room, such as permissions and titles. When you send a message or your chat room operations trigger a chat room notification, this extension will be included inNIMMessage - messageExt - roomExt
of the message (messageExt
needs to be converted toNIMMessageChat roomExtension
). -
Set the parameter when entering a chat room. Other online users in a chat room will receive a notification message that the user enters the chat room. This extension will be included in
NIMChat roomNotificationContent - notifyExt
of a chat room notification message.
Non-independent mode
The non-independent mode is simpler. When a user logs in to an IM app, call the method for entering a chat room without setting NIMChat roomIndependentMode
.
Independent mode
To enter a chat room in the independent mode, all attributes of NIMChat roomIndependentMode
are required.
NIMChatroomIndependentMode parameter list:
Parameter | Type | Description |
---|---|---|
username | NSString | User name in the independent mode. If set to nil, the SDK will use an automatically generated anonymous account to log in. In the anonymous mode, nicknames and profile picturesare required in NIMChat roomEnterRequest. |
token | NSString | Token in the independent mode. When the user name is empty, the token is invalid. |
chat roomAppKey | NSString | The AppKey of a chat room. The AppKey is optional. When the parameter is left empty, CommsEase IM AppKey will be used. |
After entering a chat room, you can set specific modes when entering the chat room by using following APIs:
@protocol NIMChat roomManager <NSObject>
/**
* Get the mode of logging in to a chat room.
*/
- (NSInteger)chat roomAuthMode:(NSString *)roomId;
- Anonymous mode and non-anonymous mode
Independent mode includes anonymous mode and non-anonymous mode. Users can receive a message and cannot send a message under anonymous mode.
When NIMChat roomIndependentMode - username
is set to nil, the anonymous mode will be activated. The SDK will log in with the automatically generated anonymous account. In the anonymous mode, nicknames and profile picturesare required in NIMChat roomEnterRequest
.
- Get the chat room address
As the independent mode does not rely on IM, the SDK can not automatically get the address of the chat room server. The client needs to request the address from the developer application server, and the application server needs the request from the CommsEase server, and then returns the result to the client. The request path: client <-> developer application server <-> CommsEase server (API: the address of requesting a chat room.).
First, register the callback method of the chat room address:
@interface NIMChat roomIndependentMode : NSObject
/**
* Register the callback method of the chat room address
*
* @param handler - The method of getting a chat room address
* @discussion - When you enter a chat room and refresh the chat room IP, the SDK will actively invoke the method and import two related parameters `roomId` & `callback`. The current callback API requires upper developers to send a network request to get related chat room address by the parameter `roomId`, and returns the address to SDK with the parameter "callback". Note: callback is required by using the parameter "callback" no matter whether the request is successful; Otherwise, a user will keep waiting after entering a chat room. Besides, register The API for only one time. If not, in case of the repeated registration, the latter will replace the former.
*/
+ (void)registerRequestChat roomAddressesHandler:(NIMRequestChat roomAddressesHandler)handler
@end
Sample codes
[NIMChat roomIndependentMode registerRequestChat roomAddressesHandler:^(NSString * _Nonnull roomId, NIMRequestChat roomAddressesCallback _Nonnull callback) {
[YourHTTPService request:roomId completion:^(NSError *error,NSArray *addresses)
{
//No matter whether the request is successful, a callback is required.
if(callback)
{
callback(error,addresses);
}
}];
}];
YourHTTPService
is the application server API of the application. The application server can call the request chat room address API of the CommsEase server to obtain the specific chat room address.
To enter a chat room in the independent mode, the following procedures are required:
- Set
NIMChat roomIndependentMode
. Please note how to obtain the method for a chat room address. - Initialize
NIMChat roomEnterRequest
and complete the assignment. - Call the method for entering a chat room.
Multi-device login to a chat room
Support setting the policy of multi-device login to the same chat room. Namely, you can specify whether users can enter the same chat room with the same account on multiple devices. You can set the policy on the CommsEase console.
- A user can be online on a device.
- A user can be concurrently online on multiple devices.
Monitor the connection status of a chat room
Entering a chat room means a new connection. Different chat rooms correspond to different connections. Developers can monitor the connection status to meet the needs of services.
@protocol NIMChat roomManagerDelegate <NSObject>
/**
* Monitor the connection status in a chat room
*
* @param roomId - Chat room ID
* @param state - Current status
*/
- (void)chat room:(NSString *)roomId
connectionStateChanged:(NIMChat roomConnectionState)state;
@end
NIMChat roomConnectionState Enumeration list
Parameter | Value | Description |
---|---|---|
NIMChat roomConnectionStateEntering | 0 | Entering a chat room. |
NIMChat roomConnectionStateEnterOK | 1 | Successfully entered a chat room. |
NIMChat roomConnectionStateEnterFailed | 2 | Failed to enter a chat room. |
NIMChat roomConnectionStateLoseConnection | 3 | Lost a connection to a chat room. |
After successfully entering a chat room, the SDK will automatically reconnect if a disconnection occurs again. Developers do not need to call the room entry API again.
When reconnecting, some network errors such as banned chat room users and the abordinary status of a chat room may occur and the following callback will be triggered. Developers should exit the chat room API in this callback.
@protocol NIMChat roomManagerDelegate <NSObject>
/**
* Errors occur when a user logs in to a chat room.
* @param roomId - Chat room ID
* @param error - Reasons for an automatic login error
*/
- (void)chat room:(NSString *)roomId
autoLoginFailed:(NSError *)error;
@end
Monitor the remove
When a user is removed from a chat room or a chat room is closed, the callback that a user is removed from a chat room is triggered:
@protocol NIMChat roomManagerDelegate <NSObject>
/**
* The callback that a user is removed from a chat room
*
* @param roomId - Chat room ID being kicked out
* @param result - Result content of being kicked out
*/
- (void)chat roomBeKicked:(NIMChat roomBeKickedResult *)result;
@end
Details of NIMChatroomBekickedResult
/**
* The result of being removed from a chat room.
*/
@interface NIMChat roomBeKickedResult : NSObject
/**
* The chat room ID that is removed from a chat room.
*/
@property (nonatomic, copy) NSString *roomId;
/**
* The reason for being removed from a chat room.
*/
@property (nonatomic, assign) NIMChat roomKickReason reason;
/**
* The extension field that is removed.
*/
@property (nonatomic, copy) NSString *ext;
@end
NIMChat roomKickReason Enumeration list
Parameter | Value | Description |
---|---|---|
NIMChat roomKickReasonInvalidRoom | 1 | The chat room has been dismissed. |
NIMChat roomKickReasonByManager | 2 | A user is removed by a chat room administrator. |
NIMChat roomKickReasonByConflictLogin | 3 | A user can not be concurrently online on multiple devices. |
NIMChat roomKickReasonBlacklist | 5 | A user is blocklisted. |
Leave a chat room
When leaving a chat room, a user is disconnected from the chat room with no messages received.
@protocol NIMChat roomManager <NSObject>
/**
* Leave a chat room
*
* @param roomId - Chat room ID
* @param completion - The callback that a user leaves a chat room
*/
- (void)exitChat room:(NSString *)roomId
completion:(NIMChat roomHandler)completion;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID. |
completion | NIMChat roomHandler | The callback that a user leaves a chat room |
Messaging in a chat room
The chat room messaging API is the same as the ordinary API of Messaging. When sending a message, set the session type as a chat room. The session ID is the chat room ID. Please note that the SDK will not locally persist chat messages in a chat room.
Notification messages in a chat room
Notification messages are generated in the following events.
NIMChat roomEventType | Description |
---|---|
NIMChat roomEventTypeEnter = 301 | A user enters a chat room. |
NIMChat roomEventTypeExit = 302 | A user leaves a chat room. |
NIMChat roomEventTypeAddBlack = 303 | A member is added to the blocklist. |
NIMChat roomEventTypeRemoveBlack = 304 | A member is removed from the blocklist. |
NIMChat roomEventTypeAddMute = 305 | Mute a user. |
NIMChat roomEventTypeRemoveMute = 306 | Unmute a user. |
NIMChat roomEventTypeAddManager = 307 | A user is set as an administrator. |
NIMChat roomEventTypeRemoveManager = 308 | Remove an administrator. |
NIMChat roomEventTypeAddCommon = 309 | A user is set as a permanent member. |
NIMChat roomEventTypeRemoveCommon = 310 | A user is removed as a permanent member. |
NIMChat roomEventTypeClosed = 311 | The chat room is closed. |
NIMChat roomEventTypeInfoUpdated = 312 | The information of the chat room is updated. |
NIMChat roomEventTypeKicked = 313 | A chat room user is removed |
NIMChat roomEventTypeAddMuteTemporarily = 314 | A chat room user is temporarily muted. |
NIMChat roomEventTypeRemoveMuteTemporarily = 315 | A chat room user is temporarily unmuted. |
NIMChat roomEventTypeMemberUpdateInfo = 316 | A chat room user has actively updated his/her information in a chat room. |
NIMChat roomEventTypeQueueChange = 317 | Notifications of chat room queue changes. |
NIMChat roomEventTypeRoomMuted = 318 | The chat room is muted. Only administrators can speak and all other members are muted. |
NIMChat roomEventTypeRoomUnMuted = 319 | Users in a chat room are unmuted. |
NIMChat roomEventTypeQueueBatchChange = 320 | Notifications of batch changes in chat room queues |
In particular, the SDK allows you to set whether to deliver notifications that users enter and leave a chat room:
- Application level: CommsEase console > Select the specific app > Deliver notifications that users enter and leave a chat room: > Enable/disable.
- A chat room: Call server API of "Disable the notification that a user enters and leaves a designated chat room".
- If you want to exclude the chat room user entry and exit messages when querying the message history of a chat room, please contact a business consultant to apply for disabling the "storage of chat room user entry and exit message history". To query historical messages of a chat room that exclude messages that users enter and leave a chat room, contact our business manager to disable " Storage of historical messages that users enter and leave a chat room."
All chat room notifications are encapsulated in the form of messages NIMMessage
. For more information on the resolution of chat room notifications, see as follows:
-
Specify whether the message is a notification message.
- Specify whether the field
NIMMessage - messageType
isNIMMessageTypeNotification
.
- Specify whether the field
-
Specify whether it is a chat room notification message.
- Convert
NIMMessage - messageObject
NIMNotificationObject
in a strong type. - Specify whether the converted field
NIMNotificationObject - notificationType
isNIMNotificationTypeChat room
.
- Convert
-
Parse the specific content.
- Convert the field
NIMNotificationObject - content
toNIMChat roomNotificationContent
in a strong type.
- Convert the field
The field description of chat room notification contents NIMChat roomNotificationContent
:
eventType
: The type of chat room notification events, which indicates the specific type of a chat room notification and is enumerated and defined byNIMChat roomEventType
.source
: The operator of a notification, which indicates the person triggering the notification and is encapsulated as the typeNIMChat roomNotificationMember
.targets
: The notified user, which indicates the user affected by this notification and is encapsulated as the typeNSArray
. Each element inNSArray
is encapsulated as the typeNIMChat roomNotificationMember
.notifyExt
: The extension field of a notification, which is defined by each operation API that triggers the notification. For example, set theNIMChat roomEnterRequest - roomNotifyExt
when entering a chat room.ext
: Only apply to temporary muting/queue events, which record the mute duration, queue operations, and other specific information.
The following shows how to parse an element change notification message in a chat room queue.
For eventType
in NIMChat roomNotificationContent
, two types of events,NIMChat roomEventTypeQueueChange
and NIMChat roomEventTypeQueueBatchChange
are included in chat room change events.
An example of message parsing:
- (void)onRecvMessages:(NSArray<NIMMessage *> *)messages
{
for (NIMMessage *message in messages)
{
if (message.messageType == NIMMessageTypeNotification)
{
if (notification.notificationType == NIMNotificationTypeChat room)
{
NIMChat roomNotificationContent *content = (NIMChat roomNotificationContent *)notification.content;
NSDictionary *info = content.ext;
if (content.eventType == NIMChat roomEventTypeQueueChange)
{
//change type
//NIMChat roomQueueChangeTypeOffer, NIMChat roomQueueChangeTypePoll, NIMChat roomQueueChangeTypeDrop,NIMChat roomQueueChangeTypeUpdate
NIMChat roomQueueChangeType changeType = [[info objectForKey:NIMChat roomEventInfoQueueChangeTypeKey] integerValue];
//key
NSString *key = [info objectForKey:NIMChat roomEventInfoQueueChangeItemKey];
//value
NSString *value = [info objectForKey:NIMChat roomEventInfoQueueChangeItemValueKey];
//deal with key and value
}
if (content.eventType == NIMChat roomEventTypeQueueBatchChange)
{
//change type
//NIMChat roomQueueBatchChangeTypePartClear
NIMChat roomQueueBatchChangeType changeType = [[info objectForKey:NIMChat roomEventInfoQueueChangeTypeKey] integerValue];
NSDictionary *batch = [info objectForKey:NIMChat roomEventInfoQueueChangeItemsKey];
for (NSString *key in batch)
{
NSString *value = [batch objectForKey:key];
//deal with key and value
}
}
}
}
}
}
changeType
parsed fromext
in the example
If eventType
of NIMChat roomNotificationContent
is NIMChat roomEventTypeQueueChange
, changeType
is NIMChat roomQueueChangeType
:
- Invalid or unknown types of change NIMChat roomQueueChangeTypeInvalid
- Add elements NIMChat roomQueueChangeTypeOffer
- Remove elements NIMChat roomQueueChangeTypePoll
- Drop elements NIMChat roomQueueChangeTypeDrop
- Update elements NIMChat roomQueueChangeTypeUpdate
If eventType
of NIMChat roomNotificationContent
is NIMChat roomEventTypeQueueBatchChange
, changeType
is NIMChat roomQueueBatchChangeType
:
- Invalid or unknown types of change NIMChat roomQueueBatchChangeTypeInvalid
- Partial drop in batches (occurs when a user drops network connection to clean the key of the user) NIMChat roomQueueBatchChangeTypePartClear
Query cloud historical messages
A chat room allows no offline messages and roaming messages. You can query historical messages in a chat room message by using following APIs. The server only stores historical messages in a chat room in the recent 10 days. URL addresses of files such as image, audio, and video sent 10 days before are still valid. But developers need to save these addresses independently for expired messages can not help you query URLs of these files. For extending "the duration of historical messages in a chat room", contact our business consultant.
@protocol NIMChat roomManager <NSObject>
/**
* Query historical messages stored in the server
*
* @param roomId - Chat room ID
* @param option - Query options
* @param result - The callback is completed.
*/
- (void)fetchMessageHistory:(NSString *)roomId
option:(NIMHistoryMessageSearchOption *)option
result:(NIMGetChat roomHistoryBlock)completion;
@end
NIMHistoryMessageSearchOption parameter list (Some fields that are invalid for the chat room message search option have been filtered.)
Parameter | Type | Description |
---|---|---|
startTime | NSTimeInterval | The start time of message retrieval, which indicates the start time for retrieving the messages. Set the parameter as 0 if there are no retrieved messages. Query forward or backward by taking that time as the starting point. |
limit | NSUInteger | The maximum number of retrieved messages is 100. |
order | NIMMessageSearchOrder | Retrieval sequence |
messageTypes | NSArray<NSNumber *> | The message type to be queried. By default, the type is nil, which indicates a full-type search. |
Information management in a chatroom
Get the chat room information
You can get the chat room information by using The API. As NIM SDK does not cache chat room information, developers need to cache the information based on services.
@protocol NIMChat roomManager <NSObject>
/**
* Get the chat room information
*
* @param roomId - Chat room ID
* @param completion - The callback that chat room information is obtained.
* @discussion - The related chat room information can be acquired only when you enter the chat room.
*/
- (void)fetchChat roomInfo:(NSString *)roomId
completion:(NIMChat roomInfoHandler)completion;
@end
Parameter List
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
completion | NIMChat roomInfoHandler | The callback that a user leaves a chat room. |
Update chat room information
@protocol NIMChat roomManager <NSObject>
/**
* Update chat room information
*
* @param request - A request for updating a chat room
* @param completion - The callback that an update is completed.
*/
- (void)updateChat roomInfo:(NIMChat roomUpdateRequest *)request
completion:(nullable NIMChat roomHandler)completion;
@end
NIMChat roomUpdateRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
updateInfo | NSDictionary | Modify information fields. The incoming data key-value pair to be updated is {@(NIMChat roomUpdateTag): NSString}. Invalid data will be filtered. |
needNotify | BOOL | Whether to generate chat room notifications |
notifyExt | NSString | The extension field included in event notifications |
Member management in a chat room
Overview of chat room members
- Chat room members include fixed members and non-fixed members. Non-fixed members include temporary members and visitors. The limit of fixed members is 1000.
- The fixed members include creator, administrator, common users, and limited users. Users with the limitation include users who are in the blocklist and permanently muted.
- instead of the creator, by default, other members are considered as visitors when added to a team.
- The visitor who was set as an administrator will become a ordinary user (not a visitor) after his administration privileges are removed.
- An administrator will become a ordinary user after his/her administration permissions are removed. The administrator cannot be set as a ordinary member.
- Only the creator can perform operations on an administrator, and an administrator cannot perform operations on the creator and other administrators.
- A ordinary user will become a visitor after his/her identity is removed.
- A visitor will become a permanent member after he/she is blocklisted. At the same time, the visitor will be disconnected from the server and cannot enter the chat room unless he/she is removed from the blocklist. The user will become a visitor after being removed from the blocklist.
- The user will become a fixed member after being muted permanently. The user will become a visitor after disabling the permanent mute. The expiry of temporary mute will not be influenced after disabling permanent mute.
- The setting and relieving of temporary muting will not change the identity of a member. If temporary mute is set repeatedly, the final expiry will cover the previous setting (without accumulation).
- The visitor is a non-fixed member in the chat room only when being online. The visitor will not be any member of the chat room if he enters and then exits from the chat room (without any relation with chat room).
Chat room member prototype:
@interface NIMChat roomMember : NSObject
/**
* User ID
*/
@property (nullable,nonatomic,copy) NSString *userId;
/**
* The field of nickname in a chat room: It is submitted when a user enters a chat room.
*/
@property (nullable,nonatomic,copy) NSString *roomNickname;
/**
* The field of profile picturesin a chat room: It is submitted when a user enters a chat room.
*/
@property (nullable,nonatomic,copy) NSString *roomAvatar;
/**
* User avatar thumbnail in a chat room
* @discussion - Only apply to use CommsEase upload server for uploading resources. Otherwise, it is invalid.
*/
@property (nullable,nonatomic,copy,readonly) NSString *roomAvatarThumbnail;
/**
* The extension field reserved for developers in a chat room: It is submitted when a user enters a chat room.
*/
@property (nullable,nonatomic,copy) NSString *roomExt;
/**
* User type
*/
@property (nonatomic,assign) NIMChat roomMemberType type;
/**
* It determines that a user is muted.
*/
@property (nonatomic,assign) BOOL isMuted;
/**
* It determines that a user is muted temporarily.
* @discussion - Temporary mute does not correlate with mute attribute.
*/
@property (nonatomic,assign) BOOL isTempMuted;
/**
* Remaining duration of temporary mute
*/
@property (nonatomic,assign) unsigned long long tempMuteDuration;
/**
* It determines that a user is added to a blocklist.
*/
@property (nonatomic,assign) BOOL isInBlackList;
/**
* It determines that a user is online. Only special members may be offline. For guests, the status can be online only.
*/
@property (nonatomic,assign) BOOL isOnline;
/**
* Timepoint of entering a chat room
*/
@property (nonatomic,assign) NSTimeInterval enterTimeInterval;
@end
Get chat room members
This API can get the list of chat room members remotely. As NIM SDK does not cache the list, developers need to cache the list based on services.
Get chat room members by paging
@protocol NIMChat roomManager <NSObject>
/**
* Get chat room members
*
* @param request - Get member request
* @param completion - A callback for completing a request
*/
- (void)fetchChat roomMembers:(NIMChat roomMemberRequest *)request
completion:(NIMChat roomMembersHandler)completion;
@end
NIMChat roomMemberRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID. |
type | NIMChat roomGetMemberType | The type of chat room members. |
lastMember | NIMChat roomMember | Anchor of the last member, excluding the last member. If it is set to nil, the query will start at the latest time of the current server, such as the first page. |
limit | NSUInteger | Get the number of chat room members. |
NIMChat roomGetMemberType Type
Parameter | Description |
---|---|
NIMChat roomGetMemberTypeRegular | Permanent members of the chat room. |
NIMChat roomGetMemberTypeTemp | Temporary members of the chat room. |
NIMChat roomGetMemberTypeRegularOnline | Online permanent members of the chat room. |
NIMChat roomGetMemberTypeUnRegularReversedOrder | Non-permanent members of the chat room (reverse query). |
Get the specified user in a chat room
@protocol NIMChat roomManager <NSObject>
/**
* Get information of chat room members by user ID
*
* @param request - Get member request
* @param completion - A callback for completing a request
*/
- (void)fetchChat roomMembersByIds:(NIMChat roomMembersByIdsRequest *)request
completion:(NIMChat roomMembersHandler)completion;
@end
NIMChat roomMembersByIdsRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
userIds | NSArray<NSString *> | List of user IDs with a maximum of 20 |
Update the user profile
@protocol NIMChat roomManager <NSObject>
/**
* Update your information in a chat room
*/
- (void)updateMyChat roomMemberInfo:(NIMChat roomMemberInfoUpdateRequest *)request
completion:(nullable NIMChat roomHandler)completion;
@end
Example:
NIMChat roomMemberInfoUpdateRequest *request = [[NIMChat roomMemberInfoUpdateRequest alloc] init];
request.roomId = @"123";
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"zhangsan" forKey:@(NIMChat roomMemberInfoUpdateTagNick)];
request.updateInfo = dic;
[[NIMSDK sharedSDK].chat roomManager updateMyChat roomMemberInfo:request
completion:^(NSError * _Nullable error) { }];
After calling this API, developers should update member object in a chat room in the memory cache.
Add/Remove an administrator
@protocol NIMChat roomManager <NSObject>
/**
* Add/remove an administrator in a chat room
*
* @param request - Update a request
* @param completion - A callback for a request
*/
- (void)markMemberManager:(NIMChat roomMemberUpdateRequest *)request
completion:(NIMChat roomHandler)completion;
@end
Adding or removing is set using NIMChat roomMemberUpdateRequest - enable
.
Add/Remove a ordinary member
@protocol NIMChat roomManager <NSObject>
/**
* Add/remove ordinary members of a chat room
*
* @param request - Update a request
* @param completion - A callback for a request
*/
- (void)markordinaryMember:(NIMChat roomMemberUpdateRequest *)request
completion:(NIMChat roomHandler)completion;
@end
Adding or removing is set using NIMChat roomMemberUpdateRequest - enable
.
Add/Remove a user who is blocklisted
@protocol NIMChat roomManager <NSObject>
/**
* Update blacklist status of a chat room for a user
*
* @param request - Update a request
* @param completion - A callback for a request
*/
- (void)updateMemberBlack:(NIMChat roomMemberUpdateRequest *)request
completion:(NIMChat roomHandler)completion;
@end
Adding or removing is set using NIMChat roomMemberUpdateRequest - enable
.
Add/Remove a user who is muted
@protocol NIMChat roomManager <NSObject>
/**
* Update the mute status of a chat room for a user
*
* @param request - Update a request
* @param completion - The callback for a request
*/
- (void)updateMemberMute:(NIMChat roomMemberUpdateRequest *)request
completion:(NIMChat roomHandler)completion;
@end
You can add or remove users who are muted by usingNIMChat roomMemberUpdateRequest - enable
.
Remove a member from a chat room
The creator or administrators can remove a user with lower permissions than themselves.
@protocol NIMChat roomManager <NSObject>
/**
* Kick special members out of a chat room
*
* @param request - Kick-out request
* @param completion - A callback for a request
*/
- (void)kickMember:(NIMChat roomMemberKickRequest *)request
completion:(NIMChat roomHandler)completion;
@end
NIMChat roomMemberKickRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
userId | NSString | User ID. Only administrators can kick out members; the creator can kick out a member with the user ID of the administrator |
notifyExt | NSString | Kicked-out notification extension filed |
Temporarily mute members
@protocol NIMChat roomManager <NSObject>
/**
* Update the temporary mute status of a chat room for a user
*
* @param request - Update a request
* @param duration - The duration of a temporary mute. Unit: second.
* @param completion - The callback for a request
*/
- (void)updateMemberTempMute:(NIMChat roomMemberUpdateRequest *)request
duration:(unsigned long long)duration
completion:(nullable NIMChat roomHandler)completion;
@end
Chat room queue
The chat room provides the queue feature, which can be used in a live co-hosting where micro sequence management is required. The permissions are determined by NIMChat room - queueModificationLevel
and can be updated using updateChat roomInfo
. By default, all users can call The API to update the queue content.
Get a chat room queue
@protocol NIMChat roomManager <NSObject>
/**
* Get a chat room queue
*
* @param roomId - Chat room ID
* @param completion - The callback for a request
*/
- (void)fetchChat roomQueue:(NSString *)roomId
completion:(nullable NIMChat roomQueueInfoHandler)completion;
@end
Example
NSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chat roomManager fetchChat roomQueue:roomId
completion:^(NSError * _Nullable error, NSArray<NSDictionary<NSString *,NSString *> *> * _Nullable info) {
if (!error)
{
//deal with info
}
else
{
//deal with errors
}
}];
Add or update queue elements
If the element is added by user A and then updated by user B, then the owner of the element is user B.
@protocol NIMChat roomManager <NSObject>
/**
* Add or update universal elements of chat room queue. The permission is determined by queueModificationLevel of NIMChat room.
*
* @param request - Request for chat room queue
* @param completion - A callback for a request
*/
- (void)updateChat roomQueueObject:(NIMChat roomQueueUpdateRequest *)request
completion:(nullable NIMChat roomHandler)completion;
@end
NIMChat roomQueueUpdateRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
key | NSString | Update the key value of the element. If the key is in the queue, update the element; Otherwise, put the key in the end of a queue. The maximum length of a key is 32 bytes |
value | NSString | The value of the updated element with a maximum length of 4,096 bytes |
transient | BOOL | Whether to delete a new element, when the user who submits the element to the chat room queue disconnects from or leaves a chat room. It is set to false to retain the element by default. When it is set to YES, after the user disconnects from or exits the chat room, the chat room will issue a notification of batch change of queue elements NIMChat roomEventTypeQueueBatchChange |
Example
NIMChat roomQueueUpdateRequest *request = [[NIMChat roomQueueUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.key = @"key";
request.value = @"value";
request.transient = YES;
[[NIMSDK sharedSDK].chat roomManager updateChat roomQueueObject:request
completion:^(NSError * _Nullable error) {
if (!error)
{
//deal with success
}
else
{
//deal with errors
}
}];
Update queue elements in batches
If the element is added by user A and then updated by user B, then the owner of the element is user B.
@protocol NIMChat roomManager <NSObject>
/**
* Update universal elements of a chat room queue in batch. The permission is determined by queueModificationLevel of NIMChat room.
*
* @param request - Requests in batch for a The chat room queue
* @param completion - The callback for a request
*/
- (void)batchUpdateChat roomQueueObject:(NIMChat roomQueueBatchUpdateRequest *)request
completion:(nullable NIMChat roomQueueBatchUpdateHandler)completion;
@end
NIMChat roomQueueBatchUpdateRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
elements | NSDictionary | The key-value pair of the elements updated in batch. The keys/values are respectively elementKey and elementValue (The maximum length of elementKey is 128 bytes, and the maximum length of elementValue is 4069 bytes). Up to 100 elements can be updated at a time. |
needNotify | BOOL | Whether to send a broadcast notification |
notifyExt | NSString | The custom field in the notification, with a maximum length of 2,048 bytes. |
Example
NIMChat roomQueueBatchUpdateRequest *request = [[NIMChat roomQueueBatchUpdateRequest alloc] init];
request.roomId = @"your_room_id";
request.needNotify = YES;
request.notifyExt = @"You have received a notification";
request.elements = dict;
[[NIMSDK sharedSDK].chat roomManager batchUpdateChat roomQueueObject:request completion:^(NSError * _Nullable error, NSArray<NSString *> * _Nullable elements) {
if (!error)
{
//deal with success
}
else
{
//deal with errors
}
}];
Remove the specified queue elements
@protocol NIMChat roomManager <NSObject>
/**
* Remove elements of a chat room queue. The permission is determined by queueModificationLevel of NIMChat room.
*
* @param request - Acquisition request
* @param completion - The callback for a request
*/
- (void)removeChat roomQueueObject:(NIMChat roomQueueRemoveRequest *)request
completion:(nullable NIMChat roomQueueRemoveHandler)completion;
@end
NIMChat roomQueueRemoveRequest parameter list
Parameter | Type | Description |
---|---|---|
roomId | NSString | Chat room ID |
key | NSString | The key value of a specified. If it is the first element, set it to empty. |
Example
NIMChat roomQueueRemoveRequest *request = [[NIMChat roomQueueRemoveRequest alloc] init];
request.roomId = @"your_room_id";
request.key = @"key";
[[NIMSDK sharedSDK].chat roomManager removeChat roomQueueObject:request completion:^(NSError * _Nullable error, NSDictionary<NSString *,NSString *> * _Nullable element) {
if (!error)
{
//deal with removed element
}
else
{
//deal with errors
}
}];
Empty a queue
@protocol NIMChat roomManager <NSObject>
/**
* Delete a chat room queue. The permission is determined by queueModificationLevel of NIMChat room.
*
* @param roomId - Chat room ID
* @param completion - The callback for a request
*/
- (void)dropChat roomQueue:(NSString *)roomId
completion:(nullable NIMChat roomHandler)completion;
@end
Example
NSString *roomId = @"your_room_id";
[[NIMSDK sharedSDK].chat roomManager dropChat roomQueue:roomId completion:^(NSError * _Nullable error) {
if (!error)
{
//deal with success
}
else
{
//deal with errors
}
}];