STSChatManager

@interface STSChatManager : NSObject

StraaS.io chat room manager, support multi-connection management.

  • Init STSChatManager with the config.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithChatManagerConfig:
    (STSChatManagerConfig *_Nullable)chatManagerConfig;

    Swift

    init(chatManagerConfig: STSChatManagerConfig?)

    Parameters

    STSChatManagerConfig

    The STSChatManagerConfig. Not to set this or sets this to nil to use the default value.

  • Connect to chat room with user JWT.

    Declaration

    Objective-C

    - (void)connectToChatroom:(nonnull NSString *)chatroomName
                      JWT:(nonnull NSString *)JWT
            eventDelegate:(nullable id<STSChatEventDelegate>)eventDelegate;

    Swift

    func connect(toChatroom chatroomName: String, jwt JWT: String, eventDelegate: STSChatEventDelegate?)

    Parameters

    chatroomName

    Identifier of chat room. Don’t pass nil or this method return early.
    JWT

    User identity information. For StraaS.io CMS member, a member JWT should be used here. Use an empty string to represent guest. Don’t pass nil or this method return early.
    eventDelegate

    Chat event delegate. Chat manager not retain this delegate.

  • Disconnect from a connected chat room.

    Declaration

    Objective-C

    - (void)disconnectFromChatroom:(nonnull STSChat *)chatroom;

    Swift

    func disconnect(fromChatroom chatroom: STSChat)

    Parameters

    chatroom

    The STSChat object you want to disconnect.

  • Get chat room active users, maximum 200 users.

    Declaration

    Objective-C

    - (void)getUsersForChatroom:(nonnull STSChat *)chatroom
                   userType:(STSGetUsersType)userType
                    success:(nonnull void (^)(NSArray<STSChatUser *> *_Nonnull))
                                success
                    failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func getUsersForChatroom(_ chatroom: STSChat, userType: STSGetUsersType, success: @escaping ([STSChatUser]) -> Void, failure: @escaping (Error) -> Void)

    Parameters

    chatroom

    The STSChat object you want to get users.
    userType

    The type of users you want to get.
    success

    Handler for successful request. It takes an NSArray of STSChatUser argument that contains chat room active users.
    failure

    Error handler.

  • Get chat room messages. Note: If there are over 5000 ccu in the chatroom, this method will return an empty array.

    Declaration

    Objective-C

    - (void)getMessagesForChatroom:(nonnull STSChat *)chatroom
                 configuration:
                     (STSGetMessagesConfiguration *_Nullable)configuration
                       success:(nonnull void (^)(
                                   NSArray<STSChatMessage *> *_Nonnull))success
                       failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func getMessagesForChatroom(_ chatroom: STSChat, configuration: STSGetMessagesConfiguration?, success: @escaping ([STSChatMessage]) -> Void, failure: @escaping (Error) -> Void)

    Parameters

    chatroom

    The STSChat object you want to get messages.
    configuration

    A STSGetMessagesConfiguration object that specifies the request rules for getting messages.
    success

    Handler for successful request. It takes an NSArray of STSChatMessage argument that contains chat room messages.
    failure

    Error handler.

  • Update nickname for guest user.

    Declaration

    Objective-C

    - (void)updateGuestNickname:(nonnull NSString *)nickname
                   chatroom:(nonnull STSChat *)chatroom
                    success:(nonnull void (^)(void))success
                    failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func updateGuestNickname(_ nickname: String, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    nickname

    New nickname. Should be between 1~20 characters.
    chatroom

    The STSChat object you want to update nickname.
    success

    Handler for successful request.
    failure

    Error handler.

  • Update role for given user.

    Declaration

    Objective-C

    - (void)updateUserRole:(nonnull NSString *)role
            targetUser:(nonnull STSChatUser *)targetUser
              chatroom:(nonnull STSChat *)chatroom
               success:(nonnull void (^)(void))success
               failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func updateUserRole(_ role: String, targetUser: STSChatUser, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    role

    The role want to be updated for target user. Role can be either kSTSUserRoleNormal or kSTSUserRoleModerator only.
    targetUser

    The users needs to be updated.
    chatroom

    The STSChat object you want to update user role.
    success

    Handler for successful request.
    failure

    Error handler.

  • Update role for given memberId.

    Declaration

    Objective-C

    - (void)updateUserRole:(nonnull NSString *)role
              memberId:(nonnull NSString *)memberId
              chatroom:(nonnull STSChat *)chatroom
               success:(nonnull void (^)(void))success
               failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func updateUserRole(_ role: String, memberId: String, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    role

    The role want to be updated for target user. Role can be either kSTSUserRoleNormal or kSTSUserRoleModerator only.
    memberId

    The CMS member id.
    chatroom

    The STSChat object you want to update user role.
    success

    Handler for successful request.
    failure

    Error handler.

  • Block users by current user. Only succeed when current user has the privilege.

    Declaration

    Objective-C

    - (void)blockUsers:(nonnull NSArray<STSChatUser *> *)users
          chatroom:(nonnull STSChat *)chatroom
           success:(nonnull void (^)(void))success
           failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func blockUsers(_ users: [STSChatUser], chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    users

    The users in chat going to be blocked
    chatroom

    The STSChat object you want to block users.
    success

    Handler for successful request.
    failure

    Error handler.

  • Revive users by current user. Only succeed when current user has the privilege.

    Declaration

    Objective-C

    - (void)reviveUsers:(nonnull NSArray<STSChatUser *> *)users
           chatroom:(nonnull STSChat *)chatroom
            success:(nonnull void (^)(void))success
            failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func reviveUsers(_ users: [STSChatUser], chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    users

    The users in chat going to be revived.
    chatroom

    The STSChat object you want to revive users.
    success

    Handler for successful request.
    failure

    Error handler.

  • Send message to chatroom. Note: Call this method more than once a second is not allowed.

    Declaration

    Objective-C

    - (void)sendMessage:(nonnull NSString *)message
           chatroom:(nonnull STSChat *)chatroom
            success:(nonnull void (^)(void))success
            failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func sendMessage(_ message: String, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    message

    Message text. Should be between 1~500 characters.
    chatroom

    The STSChat object you want to send message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Remove chat message. Note: This method works only when the current user of target chatroom has the privilege.

    Declaration

    Objective-C

    - (void)removeMessage:(nonnull NSString *)messageId
             chatroom:(nonnull STSChat *)chatroom
              success:(nonnull void (^)(void))success
              failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func removeMessage(_ messageId: String, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    messageId

    The message Id which you want to remove.
    chatroom

    The STSChat object you want to remove message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Get the pinned message of a chatroom.

    Declaration

    Objective-C

    - (void)getPinnedMessageForChat:(nonnull STSChat *)chatroom
                        success:
                            (nonnull void (^)(STSChatMessage *_Nullable))success
                        failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func getPinnedMessage(for chatroom: STSChat, success: @escaping (STSChatMessage?) -> Void, failure: @escaping (Error) -> Void)

    Parameters

    chatroom

    The STSChat object you want to get the pinned message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Pins a message to the chatroom.

    Note: 1. A chatroom can only have a pinned message at once, it means this method will override the last pinned message. 2. This method works only when the current user of target chatroom has the privilege.

    Declaration

    Objective-C

    - (void)pinMessage:(nonnull NSString *)messageId
          chatroom:(nonnull STSChat *)chatroom
           success:(nonnull void (^)(void))success
           failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func pinMessage(_ messageId: String, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    messageId

    The message Id which you want to pin.
    chatroom

    The STSChat object you want to pin the message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Unpins a message from the given chatroom. Note: This method works only when the current user of target chatroom has the privilege.

    Declaration

    Objective-C

    - (void)unpinMessageFromChatroom:(nonnull STSChat *)chatroom
                         success:(nonnull void (^)(void))success
                         failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func unpinMessage(fromChatroom chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    chatroom

    The STSChat object you want to unpin the message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Sets metadata key-value pair to a chatroom

    Note

    • This method works only when the current user of target chatroom has the privilege.
    • Sets a value to an existing key will overwrite the previous one.
    • The value should be an instance of NSString, NSNumber, NSNull or a valid JSON object. Max size is 1k if broadcast is YES, max size is 4k if broadcast is NO.
    • The key name must match the regular expression format ^[A-Za-z0-9][A-Za-z0-9_32＠#-]{0,29}$.

    Rate limit

    1 request per second per chatroom (if broadcast is YES); 1 request per 30 second per chatroom (if broadcast is NO).

    Declaration

    Objective-C

    - (void)setMetadataValue:(nonnull id)value
                  forKey:(nonnull NSString *)key
                chatroom:(nonnull STSChat *)chatroom
               broadcast:(BOOL)broadcast
                 success:(nonnull void (^)(void))success
                 failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func setMetadataValue(_ value: Any, forKey key: String, chatroom: STSChat, broadcast: Bool, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    value

    The value of metadata. Refer notes for the format constraint.
    key

    The key of metadata. Refer notes for the format constraint.
    chatroom

    The STSChat object you want to set metadata.
    broadcast

    Indicates whether the change of the metadata should be broadcasted via socket or not.
    success

    Handler for successful request.
    failure

    Error handler.

  • Gets metadata key-value pairs of a chatroom.

    Rate limit

    1 request per second per chatroom. 3000 per days per chatroom.

    Declaration

    Objective-C

    - (void)getMetadataForKeys:(NSArray<NSString *> *_Nullable)keys
                  chatroom:(nonnull STSChat *)chatroom
                   success:(nonnull void (^)(
                               NSDictionary<NSString *, STSChatMetadata *>
                                   *_Nonnull))success
                   failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func getMetadataForKeys(_ keys: [String]?, chatroom: STSChat, success: @escaping ([String : STSChatMetadata]) -> Void, failure: @escaping (Error) -> Void)

    Parameters

    keys

    The array contains keys to get. Pass nil if you want to get the metadata for all keys.
    chatroom

    The STSChat object you want to get metadata.
    success

    Handler for successful request.
    failure

    Error handler.

  • Returns the chat object.

    Declaration

    Objective-C

    - (nullable STSChat *)chatForChatroomName:(nonnull NSString *)chatroomName;

    Swift

    func chat(forChatroomName chatroomName: String) -> STSChat?

    Parameters

    chatroomName

    Identifier of chat room.

    Return Value

    A STSChat instance if the chat room is connected, or nil.

  • Returns the current chat user object.

    Declaration

    Objective-C

    - (nullable STSChatUser *)currentUserForChatroom:(nonnull STSChat *)chatroom;

    Swift

    func currentUser(forChatroom chatroom: STSChat) -> STSChatUser?

    Parameters

    chatroom

    The STSChat object you want to get current user.

    Return Value

    A STSChatUser instance if the chat room is connected, or nil.

  • Returns the cooldown to send next message for chat room.

    Declaration

    Objective-C

    - (NSTimeInterval)cooldownForChatroom:(nonnull STSChat *)chatroom;

    Swift

    func cooldown(forChatroom chatroom: STSChat) -> TimeInterval

    Parameters

    chatroom

    The STSChat object you want to get the cooldown time.

    Return Value

    The cooldown in seconds.

  • Update the chat room event delegate.

    Declaration

    Objective-C

    - (void)setEventDelegate:(nullable id<STSChatEventDelegate>)delegate
             forChatroom:(nonnull STSChat *)chatroom;

    Swift

    func setEventDelegate(_ delegate: STSChatEventDelegate?, forChatroom chatroom: STSChat)

    Parameters

    delegate

    Chat room event delegate.
    chatroom

    The STSChat object you want to set with the event delegate.

DataChannel

  • Send a key to the data channel which will be aggregated to STSAggregatedItem in chatroom:aggregatedItemsAdded:.

    Declaration

    Objective-C

    - (void)sendAggregatedDataWithKey:(nonnull NSString *)key
                         chatroom:(nonnull STSChat *)chatroom
                          success:(nonnull void (^)(void))success
                          failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func sendAggregatedData(withKey key: String, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    key

    The Aggregated item string key. Should be between 1~100 characters.
    chatroom

    The STSChat object you want to send message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Send raw data to data channel. Raw data should be a valid JSON object only. ref: https://developer.apple.com/reference/foundation/jsonserialization/1418461-isvalidjsonobject

    Declaration

    Objective-C

    - (void)sendRawData:(nonnull id)rawData
           chatroom:(nonnull STSChat *)chatroom
            success:(nonnull void (^)(void))success
            failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func sendRawData(_ rawData: Any, chatroom: STSChat, success: @escaping () -> Void, failure: @escaping (Error) -> Void)

    Parameters

    rawData

    The jsonObject raw data.
    chatroom

    The STSChat object you want to send message.
    success

    Handler for successful request.
    failure

    Error handler.

  • Get chat room aggregated data.

    Declaration

    Objective-C

    - (void)
    getAggregatedDataForChatroom:(nonnull STSChat *)chatroom
                   configuration:
                       (STSGetMessagesConfiguration *_Nullable)configuration
                         success:
                             (nonnull void (^)(
                                 NSArray<STSAggregatedData *> *_Nonnull))success
                         failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func getAggregatedData(forChatroom chatroom: STSChat, configuration: STSGetMessagesConfiguration?, success: @escaping ([STSAggregatedData]) -> Void, failure: @escaping (Error) -> Void)

    Parameters

    chatroom

    The STSChat object you want to get aggregated data.
    configuration

    A STSGetMessagesConfiguration object that specifies the request rules for getting messages.
    success

    Handler for successful request. It takes an NSArray of STSChatMessage argument that contains chat room messages.
    failure

    Error handler.

  • Get chat room raw data.

    Declaration

    Objective-C

    - (void)getRawDataForChatroom:(nonnull STSChat *)chatroom
                configuration:
                    (STSGetMessagesConfiguration *_Nullable)configuration
                      success:(nonnull void (^)(
                                  NSArray<STSChatMessage *> *_Nonnull))success
                      failure:(nonnull void (^)(NSError *_Nonnull))failure;

    Swift

    func getRawData(forChatroom chatroom: STSChat, configuration: STSGetMessagesConfiguration?, success: @escaping ([STSChatMessage]) -> Void, failure: @escaping (Error) -> Void)

    Parameters

    chatroom

    The STSChat object you want to get raw data.
    configuration

    A STSGetMessagesConfiguration object that specifies the request rules for getting messages.
    success

    Handler for successful request. It takes an NSArray of STSChatMessage argument that contains chat room messages.
    failure

    Error handler.