Chat Room

In the chat room, you can add additional information called extras that is automatically synchronized by each participant in the conversation. It is important that the amount of data stored in extras is kept minimize to ensure the quickest synchronization possible. You can use extras 'tag a room' to change background color, or you can add a latitude as well as longitude.

Create or Get 1-on-1 Chat Room with Metadata

The 1-on-1 chat room is ideal case when you want a conversation that requires 2 users. You need to set userId to identify the opponent that you want to chat to. If a chat room with predefined userId doesn't exist, it will create a new one. Otherwise, if chat room with predefined userId already exists, it will return that room and add requester and the opponents as participants. For further information you can see this Chat Room Type.

Below is the example code:

QiscusCore.shared.chatUser(userId: userId, extras: extras, onSuccess: { (room, _) in

  print("success")

}) { (error) in

  print("error \(String(describing: error?.message))")  

}

Where:

• userId (string): a user identifier that will be used to identify a user and used whenever another user need to chat with this user. It can be anything, whether is is user's email, your user database index, etc. As long as it is unique and a string.
• extras (string:any, optional): metadata that can be as additional information to chat room, which consist key-value, for example key: background, and value: red.

Create Group Chat Room with Metadata

When you want your many users to chat together in a 1-on-1 chat room, you need to create Group chat room. Basically Group chat room has the same concept as 1-on-1 chat room, but the different is that Group chat room will target array of userIds in a single method.

QiscusCore.shared.createGroupChat(name: title, userIds: participantsId, avatarURL: avatarUrl, extras: extras, onSuccess: { (room) in 

  print("success")               

}) { (error) in              

print("error create group =\(error.message)")     

}

Where:

• name (string): group name
• userIds (array of string): list of userId
• avatarUrl (string, optional): avatar URL for the group chat
• extras (string:any, optional): metadata that can be as additional information to chat room, which consist key-value, for example key: background, and value: red.

You can get created chat room from local data:

if let room =  QiscusCore.database.room.find(id: roomId){

    //success

}

Create or Get Channel with Metadata

Creating Channel chat room is ideal for a use case that requires a lot of number participants.

You need to set uniqueId to identify a Channel chat room. If a chat room with predefined uniqueId doesn't exist, it will create a new one with requester as the only one participant. Otherwise, if chat room with predefined uniqueId already exists, it will return that room and add requester as a participant.

When the chat room doesn't exist at the very first call and you do not send avatarUrl and/or name, it will use the default value. But, after the second call (room does exist) and you send avatarUrl and/or name, it will be updated to that value.

QiscusCore.shared.createChannel(uniqueId: uniqueId, name: name, avatarURL :avatarUrl, extras: extras, onSuccess: { (rooms) in

    print("success")         

}) { (error) in             

    print("error")

}

You can get created chat room from local data:

if let room =  QiscusCore.database.room.find(id: roomId){

    //success

}

Where :

• uniqueId(string): identity of a channel
• name (string): channel name
• avatarUrl (string, optional): avatar URL for channel
• extras (string:any, optional): metadata that can be as additional information to chat room, which consists of key-value, for example, key: background, and value: red.

Get Chat Room by Id (Enter Existing Chat Room)

You can enter existing chat room by using roomId and create your own chat UI. You can get roomId from chat room object that you have created or participated before for 1-on-1, Group Chat or Channel. As a return, you will get a pair of a chat room and list of messages that you can use to init data comment for the first time. As a reference, you can see the details of implementation in this in this sample.

You can use it to 1-on-1 chat room, group chat room, or Channel and here's how to get a chat room by roomId:

QiscusCore.shared.getChatRoomWithMessages(roomId: roomId, onSuccess: { (roomModel,comments) in

    print("success getting room" + roomModel)

    print("success getting comments" + comments)

}) { (error) in

     print("error \(String(describing: error?.message))")

}

Get Chat Rooms Information

You can get more than one chat room by passing list of roomId, you can set same as roomIds. You can see the participant for each room by set showParticipants to true, or you can set false to hide participant data in each room.

QiscusCore.shared.getChatRooms(roomIds: roomIds, showRemoved: showRemoved, showParticipant: showParticipant, onSuccess: { (rooms) in

     print("success")

}) { (error) in

     print(error.message)

}

Where:

• roomIds (array of room Id): list of chat room Id
• showParticipants (boolean, optional): whether to include room participant data or not, default is true, room participant data is included. This only works 1-on-1 chat and group chat, channel will not have participant in this API, you can use this Chat Room API
• showRemoved (boolean, optional): whether to show all chat rooms that previously participated, default is false, only return chat room that currently participated only

You can get chat rooms from your local data, for example:

let rooms = QiscusCore.database.room.all()

   //success    

}

Get Chat Rooms by UniqueId

You can get more than one Chat Room by passing list of uniqueIds, you can set same as roomIds. You can see the participant for each room by set showParticipants to true, or you can set false to hide participant data in each room.

QiscusCore.shared.getChatRooms(uniqueIds: uniqueIds, showRemoved: showRemoved, showParticipant: showParticipant, onSuccess: { (rooms) in   

   print("success")      

}) { (error) in  

   print(error.message)        

 }

Where:

• uniqueIds (array of room Id): list of chat room uniqueId, you can get uniqueId from chat room object
• showParticipants (boolean, optional): whether to include room participant data or not, default is true, room participant data is included. This only works 1-on-1 chat and group chat, channel will not have participant in this API, you can use this Chat Room API
• showRemoved (boolean, optional): whether to show all chat rooms that previously participated, default is false, only return chat room that currently participated only

Get Chat Room List

Get Chat Room list is an ideal case to retrieve all chat rooms that Qiscus Account has. This shows up to 100 data per page.

QiscusCore.shared.getAllChatRooms(showParticipant: showParticipant, showRemoved: showRemoved, showEmpty: showEmpty, page: page, limit: limit, onSuccess: { (rooms, meta) in

         print("success")

        }) { (error) in

            print("error")    

        }

Where:

• showParticipants(boolean, optional) : whether to include room participant data or not, default is true, room participant data is included. This only works 1-on-1 chat and group chat, channel will not have participant in this API, you can use this Chat Room API
• showRemoved (boolean, optional): whether to show all chat rooms that previously participated, default only return chat room that currently participated only
• showEmpty (boolean, optional) : whether to show all chat rooms that have been created even there are no messages or not, default is false where only chat room that have at least one message will be shown
• page(number, optional) : page number
• limit (number, optional) : number of chat rooms, max 100 data per page

Update Chat Room with Metadata

To update your chat room with metadata, you need roomId, your chat room name, your chat room avatarUrl, and extras, for example:

QiscusCore.shared.updateChatRoom(roomId:roomId, name:roomName, avatarURL: avatarUrl, extras: extras, onSuccess: { (rooms) in

 print("success")

}) { (error) in

 print(error.message)

}

Where:

• roomId(string): chat room id
• name (string): chat room name
• avatarUrl (string, optional): avatar URL for chat room
• extras (string, optional): metadata that can be as additional information to chat room, which consist key-value, for example key: background, and value: red.

Get Participant List In Chat Room

To get participant list in chat room, you need roomUniqueId, you get default 100 participants. You can get roomUniqueId from chat room object.

You can get participants in chat room by calling this method getParticipants(). You can pass your roomUniqueId within getParticipants parameters, for example:

QiscusCore.shared.getParticipants(roomUniqueId: roomUniqueId, page: page, limit:limit, sorting: sorting, onSuccess: { (participants) in

            print("success")

        }) { (error) in

            print(error.message)

        }

Where:

• roomUniqueId(string): chat room unique id
• page (number, optional): page number
• limit (number, optional): number of participant, max 100 data per page
• sorting (string, sorting): desc to sort descending based on username, asc to sort ascending based on username

Add Participant in Chat Room

You can add more than a participant in chat room by calling this method addParticipants(). You can pass multiple userIds. Once a participant succeed join the chat room, they get a new chat room in their chat room list.

QiscusCore.shared.addParticipants(roomId: roomId, userIds: userIds, onSuccess: { (participants) in

     print("sucess")               

}) { (error) in

     print("error =\(error.message)")

}

Remove Participant in Chat Room

You can remove more than a participant in chat room by calling this method removeParticipants(). You can pass multiple userIds. Once a participant is removed from the chat room, they will not find related chat room in their chat room list.

QiscusCore.shared.removeParticipants(roomId: roomId, userIds: userIds, onSuccess: { (success) in

    print("sucess")                 

}, onError: { (error) in

   print("error =\(error.message)")                     

})

Get Total Unread Count in Chat Room

You can get total unread count in every chat room that you have. Ideally, this case is used when you want to show badge icon. Below code for getting total unread count:

QiscusCore.shared.getTotalUnreadCount { (count, error) in

            if error != nil {

                print("error")

            }else{

                print("success")

            }

        }