Group Channel

A group channel is private conversation. Access to the channel requires invitation from already existing group participants. It is an ideal fit for a small group to discuss a topic privately. Also, it is suitable for direct exchange of chat messages between two users.

Creating a Group Channel

You may create a group channel in your Javascript app with the help of create() function of our GroupChannel class.

cc.GroupChannel.create(CHANNEL_NAME, PARTICIPANTS_LIST, IS_DISTINCT,  function(error, groupChannel){
  if(error == null){
    console.log("New Group Channel has been created", groupChannel)
  }
})

While creating a group channel, extra information like CUSTOM_FILTER can also be added. Use following code for this:

cc.GroupChannel.create(CHANNEL_NAME, PARTICIPANTS_LIST, IS_DISTINCT, CUSTOM_FILTER, function(error, groupChannel){
  if(error == null){
    console.log("New Group Channel has been created", groupChannel)
  }
})

CHANNEL_NAME is a string and represents the name of your group channel.
PARTICIPANTS_LIST is an Array[] of type String containing the user IDs.
IS_DISTINCT is a boolean and determines if a new group channel should be created for the same participants. You can set this boolean to true to reuse existing channel for the same set of participants.
CUSTOM_FILTER is an array which can be used to categorize group channels.

Creating One to One Private Chat

One to One Chat is a special case of Group Channel. If a group channel has 2 participants, then it is a one to one private chat. It is also recommended to use IS_DISTINCT option as true for one to one chat. It will insure that there is always a single channel between 2 users and not multiple.

cc.GroupChannel.create(CHANNEL_NAME, [CURRENT_USER_ID, SECOND_PARTICIPANT_ID], true, function(error, groupChannel){
  if(error == null){
    console.log("New Group Channel has been created", groupChannel)
  }
})

CHANNEL_NAME is a string and represents the name of your group channel.
CURRENT_USER_ID is the user id of the current user who is starting one to one chat.
SECOND_PARTICIPANT_ID is the user id with which the current user is starting chatting with.

Getting the List of all My Group Channels

To retrieve the list of all group channels of the current user, you would need to use GroupChannelListQuery class. The get() function of GroupChannelListQuery retrieves the group channel list from the server and calls the listener once the result is available.

var groupChannelListQuery = cc.GroupChannel.createGroupChannelListQuery();
groupChannelListQuery.setLimit(LIMIT);
groupChannelListQuery.setReference(REFERENCE);
groupChannelListQuery.setParticipantState(PARTICIPANT_STATE_FILTER);

groupChannelListQuery.load(function(error, groupChannelList){
  if(error == null){
    console.log("My Group Channels List Retreived", groupChannelList)
  }
})

LIMIT - Number of channels to be retrieved. The default is 20.
REFERENCE - Reference group channel's ID.
PARTICIPANT_STATE_FILTER - Possible values are "ALL", "INVITED", "ACCEPTED"

Getting a Group Channel with ID

You may retrieve a particular group with the help of its ID by calling GroupChannel.get(). This function takes Group Channel ID as argument along with callback listener.

cc.GroupChannel.get(CHANNEL_ID, function(error, groupChannel){
  if(error == null){
    console.log("Group Channel retrieved successfully", groupChannel)
  }
})

Updating Metadata of Group Channel

groupChannel.updateMetadata(METADATA, function(error, groupChannel){
  if(error == null){
    console.log("Metadata updated successfully")
  }
})

Metadata - It is an object in the form of key-value pair. Ex - {"a": "1", "b": "2"}

Inviting Participants to Group Channel

Already existing participants of the group channel can invite more users to join the channel.

groupChannel.inviteParticipants(PARTICIPANT_IDs, function(error){
  if(error == null){
    console.log("Participants added successfully")
  }
})

PARTICIPANT_IDs is an array of user_ids(string).
Please note that inviteParticipants() is a function of an instance of GroupChannel class.

Accept Invitation to Group Channel

Participants on getting an invitation to join a group channel need to accept the invitation to participate in the channel

groupChannel.acceptInvitation(function(error){
  if(error == null){
    console.log("Invitation accepted successfully")
  }
})

Decline Invitation of Group Channel

Participants on getting an invitation to join a group channel can also decline the invitation.

groupChannel.declineInvitation(function(error){
  if(error == null){
    console.log("Invitation accepted successfully")
  }
})

Leaving Group Channel

A participant of a group channel can leave the channel if she no longer wants to receive messages or notification from the channel.

groupChannel.leave(function(error){
  if(error == null){
    console.log("channel left successfully")
  }
})

Sending Messages in Channel

A participant of a group channel can send two types of messages in it:

TEXT: a normal text message
ATTACHMENT: a binary attachment like image, document etc.

Sending Text Message

groupChannel.sendMessage(MESSAGE, function(error, message){
  if(error == null){
    console.log("Message sent successfully", message)
  }
})

Addition properties can be sent with a message like MetaData, CustomFilter.

groupChannel.sendMessage(MESSAGE, METADATA, CUSTOM_FILTER, function(error, message){
  if(error == null){
    console.log("Message sent successfully", message)
  }
})

MESSAGE - Text message which needs to be sent.
METADATA - Javascript Object which can be used to store additional details about a message.
CUSTOM_FILTER - Array[] of type String which can be used to categorize messages.

Sending Attachment

groupChannel.sendAttachment(ATTACHMENT, function(progress, total){
  console.log("Tracking progress of upload", progress, total)
}, function(error, message){
  console.log("Attachment sent successfully", message)
})

Receiving Messages

In ChatCamp, ChannelListener is used to handle information from server. This information can be a new chat message, new group channel created by some other user etc.

To receive message in a group channel, onGroupChannelMessageReceived ChannelListener is used.

let channelListener = new cc.ChannelListener();
channelListener.onGroupChannelMessageReceived = function(groupChannel, message) {
  console.log("Message successfully received in group channel")
}
cc.addChannelListener(LISTENER_ID, channelListener)

Retrieving Previous Messages

Previous messages of a group channel can be retrieved. It can only be retrieved by participants of the group channel.

let previousMessageListQuery = groupChannel.createPreviousMessageListQuery();

previousMessageListQuery.setLimit(LIMIT);
previousMessageListQuery.setReference(REFERENCE);
previousMessageListQuery.setSortBy(SORT_BY);

previousMessageListQuery.load(function(previousMessageListQueryError, messages) {
  if(!previousMessageListQueryError){
    console.log("Previous messages are successfully loaded")
  }
}

LIMIT is the number of previous messages required to be loaded.
REFERENCE is the reference message_id. Messages older than this message_id will be loaded. In case to load most recent messages, pass REFERENCE as null.
SORT_BY means to sort the list by most recently sent and most recently updated. Possible values are "INSERTED_AT" or "UPDATED_AT"

Typing Indicators

Typing indicators can be shown in chat using functions startTyping() and stopTyping(). These are functions of instance of GroupChannel class.

cc.GroupChannel.get(CHANNEL_ID, function(error, groupChannel){
  //groupChannel is the instance of GroupChannel class
  groupChannel.startTyping()
  groupChannel.stopTyping()
})

Receiving Typing Indicators

Typing indicators sent by other users in the group channel can be handled using ChannelListener functionality of ChatCamp SDK. For Typing indicator, onGroupChannelTypingStatusChanged is used. It is similar to how we learnt about Receiving Messages in above sections.

let channelListener = new cc.ChannelListener();
channelListener.onGroupChannelTypingStatusChanged = function(groupChannel) {
  console.log("Typing", groupChannel, groupChannel.getTypingParticipants())
}
cc.addChannelListener(LISTENER_ID, channelListener)

Read Receipt

Current user can mark all messages of a group channel as read by calling function markAsRead() of instance of GroupChannel class.

groupChannel.markAsRead()

Getting List of Participants

List of participants of a group channel can be accessed through groupChannel instance of GroupChannel class. participants attribute of groupChannel, is an array of participant objects for this particular groupChannel.

let channel_participants = groupChannel.participants

Updating a message in Group Channel

A participant can update his message in the group channel. A participant is not authorized to update message of other participants.

messageParams = new cc.MessageParams();
messageParams.setText(TEXT);
messageParams.setCustomFilter(CUSTOM_FILTER);
messageParams.setData(DATA);
messageParams.setMetadata(METADATA);

groupChannel.updateMessage(MESSAGE_ID, messageParams, function(error, message){
	if(error == null){
		console.log("Message Updated Successfully")
	}
));

Group Channel Sync

Group Channel details stored locally in groupChannel instance need to be synched with server in case local data becomes stale due to chat disconnect. ChatCamp provides sync() function for this.

groupChannel.sync(function(error, groupChannel){
  console.log("Updated group channel", groupChannel)
})