Instant Messaging
iOS
Getting Started
Product Introduction
Overview
Features
Feature overview
Account Integration and Login
Basic Message Features
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Limits
Development Integration
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
System Notification
APNs
Superteam
Chat Room
Anti-spam
Chat Extension
Miscellaneous Features
Reference Documents
Configuration Instruction for PushKit
Push Configuration for Apple iOS
API References
iOS API Reference
Status Codes

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 in NIMMessage - messageExt - roomExt of the message (messageExt needs to be converted to NIMMessageChat 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:

  1. Specify whether the message is a notification message.

    • Specify whether the field NIMMessage - messageType is NIMMessageTypeNotification.
  2. Specify whether it is a chat room notification message.

    • Convert NIMMessage - messageObject NIMNotificationObject in a strong type.
    • Specify whether the converted field NIMNotificationObject - notificationType is NIMNotificationTypeChat room.
  3. Parse the specific content.

    • Convert the field NIMNotificationObject - content to NIMChat roomNotificationContent in a strong type.

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 by NIMChat roomEventType.
  • source: The operator of a notification, which indicates the person triggering the notification and is encapsulated as the type NIMChat roomNotificationMember .
  • targets: The notified user, which indicates the user affected by this notification and is encapsulated as the type NSArray. Each element in NSArray is encapsulated as the type NIMChat 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 from ext 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
    }
}];
Was this topic helpful?
Yes
No
  • Overview
  • Enter a chat room
  • Non-independent mode
  • Independent mode
  • Multi-device login to a chat room
  • Monitor the connection status of a chat room
  • Monitor the remove
  • Leave a chat room
  • Messaging in a chat room
  • Notification messages in a chat room
  • Query cloud historical messages
  • Information management in a chatroom
  • Get the chat room information
  • Update chat room information
  • Member management in a chat room
  • Overview of chat room members
  • Get chat room members
  • Get chat room members by paging
  • Get the specified user in a chat room
  • Update the user profile
  • Add/Remove an administrator
  • Add/Remove a ordinary member
  • Add/Remove a user who is blocklisted
  • Add/Remove a user who is muted
  • Remove a member from a chat room
  • Temporarily mute members
  • Chat room queue
  • Get a chat room queue
  • Add or update queue elements
  • Update queue elements in batches
  • Remove the specified queue elements
  • Empty a queue