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 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 Chat Room Type section.

Below is the example code:

Javascript
    
 
qiscus.chatTarget(userId, options)    .then(function (room) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Where:

userId: 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.
options: 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.

Javascript
    
​x
 
options = { avatarURL : "http://avatar_url" //other data}​qiscus.createGroupRoom(roomName, userIds, options)    .then(function (room) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Where:

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

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.

Javascript
    
 
qiscus.getOrCreateRoomByChannel(uniqueId, name, avatarURL)    .then(function (room) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Where :

uniqueId: identity of a channel
name: 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 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 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:

Javascript
    
 
qiscus.getRoomById(roomId)    .then(function (room) {        // On success get room,            room = room      // On success get comments,            comments = room.comments      })    .catch(function (error) {        // On error    })
Copy

Get Chat Room Information

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

Javascript
    
 
var params = {  room_ids: ["roomId1", "roomId2"],  room_unique_ids: ["roomUniqueId1", "roomUniqueId2"],  show_participants: false, show_removed : false}​qiscus.getRoomsInfo(params)    .then(function (rooms) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Where:

room_ids (array of room Id, optional): list of chat room Id. This optional if you pass the room_unique_id
room_unique_Ids (array of room unique id, optional): list of chat room unique id
show_participants (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 ideal case to retrieve all Chat Rooms that Qiscus Account has. This shows up to 100 data per page.

Javascript
    
 
var params = {  page: 1,  limit: 100, show_participants: false, show_empty : false}​qiscus.loadRoomList(params)    .then(function (rooms) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Where:

show_participants (boolean, optional) : whether to include room participant data or not, default is false, 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
show_empty (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 (int, optional) : page number
limit (int, optional) : number of chat rooms, max 100 data per page

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:

Javascript
    
 
var params = {  id: 12345,  room_name: "hello", avatar_url: "http://avatar_url", options : {} // object}​qiscus.updateRoom(params)    .then(function (room) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Where:

id: chat room id
room_name: room name
avatar_url: 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 get default 100 participants.

You can get participants in Chat Room by calling this method getRoomParticipants. You can pass your roomUniqueId within getRoomParticipants parameters, for example:

Javascript
    
 
var roomUniqueId = 'room-unique-id'var page = 1var limit = 20​qiscus.getParticipants(roomUniqueId, page, limit)  .then(function (participants){    // Do something with participants  })  .catch(function (error) {    // Do something if error occured  })
Copy

Default return 100 participants for each page.

Add Participant in Chat Room

You can add more than a participant in Chat Room by calling this method addParticipantsToGroup. You can pass multiple userIds. Once a participant succeed join the Chat Room, they get a new Chat Room in their Chat Room list.

Javascript
    
 
qiscus.addParticipantsToGroup(roomId, [userIds])    .then(function (users) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Remove Participant in Chat Room

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

Javascript
    
 
qiscus.removeParticipantsFromGroup(roomId, [userIds])    .then(function (users) {        // On success    })    .catch(function (error) {        // On error    })
Copy

Get Total Unread Count in Chat Room

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

Javascript
    
 
qiscus.getTotalUnreadCount()    .then(function (unreadCount) {        // On success    })    .catch(function (error) {        // On error    })
Copy

This API is deprecated

Last updated on

Was this page helpful?