Chat Room

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

Options consist of string key-value pairs.

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 section.

Below is the example code:

Java
    
 
QiscusApi.getInstance().getChatRoom(userId, distinctId, options);
Copy

Where:

userId: a User identifier that will be used to identify a user and used whenever another user needs to chat with this user. It can be anything, whether is user's email, your user database index, etc. as long as it is unique and a string.
distinctId: (deprecated) you can fill “ ” (empty string).
options: metadata that can be as additional information to Chat Room, which consists key-value, for example, key: background, and value: red.

If you want to save the Chat Room into local data after creating or getting Chat Room from Qiscus server, here's the code:

Java
    
 
QiscusApi.getInstance().getChatRoom(userId, distinctId, options)        .doOnNext(chatRoom -> QiscusCore.getDataStore().addOrUpdate(chatRoom))        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoom -> {           // on success                 }, throwable -> {            // on error                });
Copy

We recommend after creating or getting a Chat Room, you need to update to your local data.

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 difference is that Group Chat Room will target array of userIds in a single method.

Java
    
 
QiscusApi.getInstance().createGroupChatRoom(roomName, userIds, avatarUrl, options)        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoom -> {            // on success                 }, throwable -> {           // on error                 });
Copy

Where:

roomName: group name
userIds: list of userId
avatarUrl: avatar url for group Chat Room
options: metadata that can be as additional information to Chat Room, which consists of key-value, for example, key: background, and value: red.

After successfully creating a Chat Room, you can save Chat Room into local data like this:

Java
    
 
QiscusCore.getDataStore().addOrUpdate(chatRoom);
Copy

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 room doesn't exist at the very first call and you do not send avatarUrl and/or roomName, it will use the default value. But, after the second call (room does exist) and you send avatarUrl and/or roomName, it will be updated to that value.

Java
    
 
QiscusApi.getInstance().getGroupChatRoom(uniqueId, roomName, avatarUrl, options)        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoom -> {         // on success                 }, throwable -> {         // on error                 });
Copy

You can get Channel from your local data, for example:

Java
    
 
QiscusCore.getDataStore().getChatRoomWithUniqueId(uniqueId);
Copy

Where :

uniqueId : identity of a Channel
roomName: Channel name
avatarUrl: avatar url for Channel
options: 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 QiscusChatRoom 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 Comments that you can use to init data comment for the first time. As a reference, you can see the details of implementation 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:

Java
    
 
QiscusApi.getInstance().getChatRoomComments(roomId)        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoomListPair -> {         // on success getting chat room          QiscusChatRoom qiscusChatRoom = chatRoomListPair.first;         // on success getting comments          List<QiscusComment> comments = chatRoomListPair.second;        }, throwable -> {         // on error        });
Copy

Get Chat Room Information

You can get more than one Chat Room, by passing a list of roomIds. While uniqueIds will deprecate soon, now you can set uniqueIds value with the same roomIds. You can see the participant for each room by setting showMembers to be true, or you can set it into false to hide participant data in each room.

Java
    
 
QiscusApi.getInstance().getChatRooms(roomIds, uniqueIds, showMembers)        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoomList -> {          // on success           }, throwable -> {         // on error         });
Copy

You can get Chat Rooms from your local data, for example:

Java
    
 
QiscusCore.getDataStore().getChatRooms(roomIds, uniqueIds);
Copy

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.

Java
    
 
QiscusApi.getInstance().getChatRooms(page, limit, showMembers)        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoomList -> {          // on success           }, throwable -> {         // on error         });
Copy

You can get Chat Room List from your local data, for example:

Java
    
​x
 
QiscusCore.getDataStore().getChatRooms(limit, offset);​//or only using limit​QiscusCore.getDataStore().getChatRooms(limit);
Copy

You need to update your local data from Qiscus Server, for example:

Java
    
 
QiscusApi.getInstance().getChatRooms(page, limit, showMembers)    .doOnNext(chatRooms -> {        for (QiscusChatRoom chatRoom : chatRooms) {            QiscusCore.getDataStore().addOrUpdate(chatRoom);        }    })    .subscribeOn(Schedulers.io())    .observeOn(AndroidSchedulers.mainThread())    .subscribe(chatRooms -> {        //on success    }, throwable -> {        //on error    });
Copy

Update Chat Room with Metadata

To update your Chat Room metadata, you need roomId, your Chat Room roomName, your Chat Room avatarUrl, and options, for example:

Java
    
 
QiscusApi.getInstance().updateChatRoom(roomId, roomName, avatarUrl, options)        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoom -> {         // on success        }, throwable -> {         // on error        });
Copy

Where:

roomId: Chat Room Id
roomName: room name
avatarUrl: avatar URL
options: metadata that can be as additional information to Chat Room, which consist key-value, for example key: background, and value: red.

Update chat room API works only for Group chat and Channel

Get Participant List In Chat Room

To get participant list in Chat Room, you need roomUniqueId, you can get roomUniqueId within chat room object. By default you get 100 participants, for example:

Java
    
 
QiscusApi.getInstance().getRoomMembers(roomUniqueId);
Copy

You can get advanced data by adding some parameters, for example, you can order the list based on either ascending (asc) or descending (desc), or you can sort by username.

Java
    
 
QiscusApi.getInstance().getRoomMembers(roomUniqueId, offset, sorting, userName, metaRoomMembersListener);
Copy

Here's an example to retrieve participant with additional parameters:

Java
    
 
QiscusApi.getInstance().getRoomMembers("roomuniqueid", 0, null, null, null, (currentOffset, perPage, total) -> {                    /**                     you can get currentOffset, perPage, and total here                     * currentOffset -> current offset the data                     * perPage -> limit data = 100                     * total -> total data                     */                })                .subscribeOn(Schedulers.io())                .observeOn(AndroidSchedulers.mainThread())                .subscribe(qiscusRoomMembers -> {                    // success: now you can qiscusRoomMembers here                }, throwable -> {                    // error :show error here                });
Copy

Where:

roomUniqueId: uniqueId of Chat Room,
offset: number of offset,
sorting: filtering based on ascending (asc) or descending (desc) , by default refers to asc,
username: (deprecated) filtering based on the participant's username,
metaRoomMemberListener: metadata from the response Qiscus Server. There are total page, current offset, and page.

Default return 100 participants for each page.

Add Participant in Chat Room

You can add more than a participant in Chat Room by calling addRoomMember method. You can also pass multiple userIds. Once a participant succeeds to join the Chat Room, they will get a new Chat Room in their Chat Room list.

Java
    
 
QiscusApi.getInstance().addRoomMember(roomId, userId);
Copy

After succeed to add participant in Chat Room, you can update Chat Room object to local data, for example:

Java
    
 
QiscusApi.getInstance().addRoomMember(roomId, userId)        .doOnNext(chatRoom -> QiscusCore.getDataStore().addOrUpdate(chatRoom))        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoom -> {           // on success        }, throwable -> {            //on error                });
Copy

Remove Participant in Chat Room

You can remove more than a participant in Chat Room by calling removeRoomMember method_._ You can also pass multiple userId. Once a participant is removed from the Chat Room, they will not find related Chat Room in their Chat Room list.

Java
    
 
QiscusApi.getInstance().removeRoomMember(roomId, userId)
Copy

After succeed to remove a participant in Chat Room, you can update Chat Room object to local data to keep the data updated, for example:

Java
    
 
QiscusApi.getInstance().removeRoomMember(roomId, userId)        .doOnNext(chatRoom -> QiscusCore.getDataStore().addOrUpdate(chatRoom))        .subscribeOn(Schedulers.io())        .observeOn(AndroidSchedulers.mainThread())        .subscribe(chatRoom -> {           //success        }, throwable -> {            //error                });
Copy

Get Total Unread Count in Chat Room (Deprecated)

You can get total unread count in every Chat Room. Ideally, this case is used when you want to show a badge icon. For example, getting total unread count please see the code below:

Java
    
 
QiscusApi.getInstance().getTotalUnreadCount()            .subscribeOn(Schedulers.io())            .observeOn(AndroidSchedulers.mainThread())            .subscribe(totalUnreadCount -> {                //success            }, throwable -> {                //error                    })
Copy

Last updated on

Was this page helpful?