Group channel: Advanced

This page explains the advanced features for group channels.

If the startTyping() and endTyping() methods are called while the current user is typing a text message in a group channel, the onTypingStatusUpdated() in the channel event handler will be invoked on all channel members' devices except the one that belongs to the current user.

groupChannel.startTyping();
groupChannel.endTyping();
...

// To listen to an update from all the other channel members' client apps, implement the onTypingStatusUpdated() with things to do when notified.
var channelHandler = new sb.ChannelHandler();
channelHandler.onTypingStatusUpdated = function(groupChannel) {
    var members = groupChannel.getTypingMembers();
    // Refresh typing status of members within channel.
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

To mark messages as delivered when an online group channel member receives the message from Sendbird server, the markAsDelivered() method should be called. For offline group channel members, the markAsDelivered() should be called when they come back from the background or go back online.

sb.markAsDelivered(CHANNEL_URL);

sb.GroupChannel.getChannel(CHANNEL_URL, (channel, error) => {
    if (error) {
        // Handle error.
    }

    channel.markAsDelivered();
    ...
});

When a message is delivered to an online group channel member, it is automatically marked as delivered and the other online members are notified of delivery receipt through the onDeliveryReceiptUpdated() method in the channel event handler. However, when it is delivered to an offline group channel member as a push notification, the message can be marked as delivered through the groupChannel.markAsDelivered(), and other online members are notified of the delivery receipt through the onDeliveryReceiptUpdated().

var channelHandler = new sb.ChannelHandler();

channelHandler.onDeliveryReceiptUpdated = channel => {
    ...
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

To keep the most up-to-date and accurate read status of messages for all group channel members, the markAsRead() method should be called every time one of the members reads messages by entering the channel from a channel list or bringing the opened channel view to the foreground.

If the current user opens a channel and the markAsReadAll() is called, Sendbird server will update both the unread message count of the individual channel and the total unread message count of all the group channels joined by the user. The server then notifies the change of read status to all members' devices through the onReadReceiptUpdated() method in the channel event handler, except the one that is being used by the current user.

Note : When a channel member sends a message to the channel, Sendbird server updates the member's read receipt to the time when the message has sent. Meanwhile, the read receipts of other channel members can be updated when the markAsRead() method is called. If a new member joins the channel, the method works differently based on the value of the display_past_message property of your Sendbird application. If the property is set to true, the new member’s read receipt will be updated to the sent time of the last message in the channel. If false, it will be updated to 0.

// Call the 'markAsRead()' when the current user views unread messages in a group channel.
groupChannel.markAsRead().then(()=>{
    // MarkAsRead Succeeded
})
.catch(err=>{
    console.error('MarkAsRead Fail = ', err);
});
...

// To listen to an update from all the other channel members' client apps, implement the onReadReceiptUpdated() with things to do when notified.
var channelHandler = new sb.ChannelHandler();

channelHandler.onReadReceiptUpdated = function(groupChannel) {
    if (currentGroupChannel.url === groupChannel.url) {
        // For example, code for redrawing a channel view.
    }
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

Note: The display_past_message property determines whether to display past messages to newly joined members when they enter the channel. This property is also linked to the Chat history option, which can be adjusted in your dashboard under Settings > Chat > Channels > Group channels.

You can retrieve the number of members who haven’t received a specific message in a group channel. If zero is returned, it means that the message has been delivered to all the other members.

const param = new sb.GroupChannelParams();
param.addUsers([USER_2, USER_3]);

sb.GroupChannel.createChannel(param, (channel, error) => {
    if(error) {
        // Handle error.
    }

    channel.sendUserMessage('Hi Sendbirdians!', (message, error) => {
        if (error) {
            // Handle error.
        }

        int numberOfUndeliveredMembers = channel.getUndeliveredMemberCount(message);    // The number of members who haven’t received the message.
        ...
    });
});

Using the getReadMembers() method, you can view members who have read a specific message in a group channel. The method returns a list of channel members who have read the message by comparing the message’s creation time and the channel members’ read receipt. The list will exclude the current user and the message sender.

Note: Read receipt indicates the timestamp of the latest time when each user has read messages in the channel, in Unix milliseconds.

If you want to keep track of who has read a new message, we recommend that you use the getReadMembers() in the onReadReceiptUpdated(). Then the client app will receive a callback from Sendbird server whenever a channel member reads a message. To do so, you should pass the new message object as an argument to a parameter in the getReadMembers() through the onReadReceiptUpdated().

var readMembers = groupChannel.getReadMembers(MESSAGE);

Note: Using the getUnreadMembers() method, you can also view members who have not read a specific message in a group channel, except the current user and the message sender. In the meantime, you can get information on each channel member's read receipt through the getReadStatus() method.

Using the getReadReceipt() method, you can get the number of members who have not read a specific message in a group channel. To get the exact value, the channel should be updated first through the markAsRead() before calling the getReadReceipt().

// Call the markAsRead() when the current user views unread messages in a group channel.
groupChannel.markAsRead().then(()=>{
    // MarkAsRead Succeeded
})
.catch(err=>{
    console.error('MarkAsRead Fail = ', err);
});
...

// To listen to an update from all the other channel members' client apps, implement the onReadReceiptUpdated() with things to do when notified.
var channelHandler = new sb.ChannelHandler();
channelHandler.onReadReceiptUpdated = function(groupChannel) {
    if (currentGroupChannel.url === groupChannel.url) {
        ...

        for (let message of messages) {
            var unreadCount = groupChannel.getReadReceipt(message);
            if (unreadCount <= 0) {
                // All members have read the message.
            } else {
                // Some of members haven't read the message yet.
            }
        }
    }
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

You can view the last message of a group channel.

groupChannel.lastMessage;

You can retrieve the total number of the current user's unread messages in a group channel.

groupChannel.unreadMessageCount;

You can retrieve the total number of the current user's unread messages in all joined group channels.

sb.getTotalUnreadMessageCount(function(count, error) {
    if (error) {
        // Handle error.
    }

    ...
});

You can retrieve the total number of the current user's joined group channels which one or more unread messages.

sb.getTotalUnreadChannelCount(function(count, error) {
    if (error) {
        // Handle error.
    }

    ...
});

You can send admin messages to a group channel using Sendbird Dashboard or Chat Platform API. To send an admin message through your dashboard, go to the Chat > Group channels, select a group channel, find the message box below, click the Admin message tab, and then write your message in the box. An admin message is limited to 1,000 characters.

Unlike other types of messages, a push notification for an admin message is not available by default. If you want assistance on this, contact our sales team.

You have the option to create further actions in a channel by using extra data in a message. You can add one or more key-values items to a message which you can save, update, or remove, when necessary. Based on those items, you can design and implement several different actions such as measuring user engagement within a chosen time limit through polls or counting how many times a message has been copied by members.

Note: For the quality of performance, every Sendbird application has its own limits to how many key-values items you can add to a single message, as well as the maximum number of values an item can have. If you would like more information on these limits, contact our sales team.

// When a message has been successfully sent to a channel, create items with keys.
groupChannel.createMessageMetaArrayKeys(MESSAGE, ['referees', 'games'], function(message, error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Adding values to specific items by their keys.
var valuesToAdd = {
    'referees': ['John', 'Brandon', 'Harry', 'Jay'],
    'games': ['soccer', 'baseball', 'basketball']
};

groupChannel.addMessageMetaArrayValues(MESSAGE, valuesToAdd, function(message, error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Removing existing values of specific items by their keys.
var valuesToRemove = {
    'referees': ['Brandon', 'Jay']
};

groupChannel.removeMessageMetaArrayValues(MESSAGE, valuesToRemove, function(message, error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Deleting items by their keys.
groupChannel.deleteMessageMetaArrayKeys(MESSAGE, ['referees', 'games'], function(message, error) {
    if (error) {
        // Handle error.
    }

    ...
});

To get the key-values items of a message, read the message.metaArrays.

The Chat SDK supports the URL link preview when a message text contains the URL of a web page.

Note: This feature is turned on by default for Sendbird applications. If this isn't available for your Sendbird application, contact our support team to enable the feature.

To view the image in full screen, click on the

OGMetaData is a class that holds the Open Graph (OG) protocol-related data, including the four properties: title, URL, description, and image of an OG object.

Note: Some websites don’t provide the OG metadata fields mentioned above. In that case, even though the Open Graph protocol states them as requirements, all of the four fields can be null.

OGImage is a class that holds image-related data for an OGMetaData object. The OGImage class can also have six optional structured properties of URL, secure URL, type, width, height, and alt.

Note: Except for width and height, other fields such as URL, secure URL, type, and alt can be null. If the target website doesn’t provide width and height data, the value of those two fields are set to 0.

If a user sends a message with a web page URL and the linked web page possesses Open Graph (OG) tags, or OG metadata, Sendbird server parses the message content, extracts the URL in the message, gets the OG metadata from it, and creates an OG metadata object for the message. Then message recipients will get the parsed message with its OG metadata object through the onMessageReceived() method in the channel event handler of the SDK. On the other hand, the message sender will do the same through the onMessageUpdated().

Displaying an OG metadata object is available for two subtypes of BaseMessage: UserMessage and AdminMessage. If the content of a BaseMessage object includes a web page URL containing OG metadata, the onMessageReceived() method returns OGMetaData and OGImage objects.

If Sendbird server doesn’t have cache memory of the OG metadata of the given URL, the BaseMessage.ogMetaData can be null due to the time it takes to fetch the OG metadata from a remote web page. In the meantime, the message text containing the URL will be delivered first to message recipients’ client app through the onMessageReceived() method. When the server completes fetching, the onMessageUpdated() method will be called and the message with its OG metadata object will be delivered to the recipients’ client app. However, if Sendbird server has already cached the OG metadata of the URL, the BaseMessage.ogMetaData returns the message and its OGMetaData object instantly and the onMessageUpdated() method won’t be called.

// Send a user message containing the URL of a web page.
const params = new sb.UserMessageParams();
params.message = 'sendbird.com';
...

groupChannel.sendUserMessage(params, function(message, error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Receive a user message containing OG metadata of the web page through a channel event handler.
const channelHandler = new sb.ChannelHandler();

channelHandler.onMessageReceived = (channel, message) => {
    if (message.ogMetaData) {
        // You can create and customize the URL link preview by using the Open Graph metadata of the message.
        var url = message.ogMetaData.url;
        var width = message.ogMetaData.width;
        ...

    } else {
        // If the message.ogMetaData is null, wait until the onMessageUpdated() method receives a callback from Sendbird server.
    }

    ...
};

channelHandler.onMessageUpdated = (channel, message) => {
    if (message.ogMetaData) {
        // You can create and customize the URL link preview by using the Open Graph metadata of the message.
        var url = message.ogMetaData.url;
        var width = message.ogMetaData.width;
        ...

    }

    ...
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

When creating a group channel, you can additionally specify a custom channel type to subclassify group channels. This custom type takes on the form of a String, and can be useful in searching or filtering group channels.

The data and customType property of a channel object allow you to append information to your channels. While both properties can be used flexibly, common examples for the customType include categorizing channels into School or Work.

var params = new sb.GroupChannelParams();
params.addUserIds(['James', 'Chris']);
params.name = NAME;
params.customType = CUSTOM_TYPE;
...

sb.GroupChannel.createChannel(params, function(groupChannel, error) {
    if (error) {
        // Handle error.
    }

    ...
});

To get a channel's custom type, read the groupChannel.customType.

When sending a message, you can additionally specify a custom message type to subclassify messages. This custom type takes on the form of a String, and can be useful in searching or filtering messages.

The data and customType properties of a message object allow you to append information to your messages. While both properties can be used flexibly, common examples for the customType include categorizing message groups into Notes or Contacts.

To embed a custom type into your message, assign a value to the customType under the UserMessageParams or FileMessageParams object. Then, pass the specified object as an argument to the parameter in the sendUserMessage() or sendFileMessage() method.

const params = new sb.UserMessageParams();
params.message = TEXT_MESSAGE;
params.customType = CUSTOM_TYPE;
...

groupChannel.sendUserMessage(params, function(userMessage, error) {
    if (error) {
        // Handle error.
    }

    ...
});

To get a message's custom type, read the userMessage.customType.

You can search for specific group channels by using several types of search filters within GroupChannelListQuery and PublicGroupChannelListQuery classes.

A GroupChannelListQuery instance provides many types of search filters such as ChannelNameContainsFilter and ChannelUrlsFilter. You can use these filters to search for specific private group channels.

The sample code below shows the query instance, which returns a list of the current user's group channels that partially match the specified keyword in the ChannelNameContainsFilter in the channels' name.

var listQuery = sb.GroupChannel.createMyGroupChannelListQuery();
listQuery.includeEmpty = true;
listQuery.channelNameContainsFilter = 'Sendbird';

listQuery.next(function(groupChannels, error) {
    if (error) {
        // Handle error.
    }

    // Through "groupChannels" parameter of the callback function, which Sendbird server has passed a result list to,
    // a list of group channels that have 'Sendbird' in their names is returned.
    ...
});

The following shows the query instance, which returns a list of the current user's group channels that partially match the specified keyword in the ChannelUrlsFilter in the channels' URL.

var listQuery = sb.GroupChannel.createMyGroupChannelListQuery();
listQuery.includeEmpty = true;
listQuery.channelUrlsFilter = ['seminar', 'lecture'];

listQuery.next(function(groupChannels, error) {
    if (error) {
        // Handle error.
    }

    // Through "groupChannels" parameter of the callback function, which Sendbird server has passed a result list to,
    // a list of group channels that have 'seminar' or 'lecture' in their URLs is returned.
    ...
});

The following table shows all supported filters for GroupChannelListQuery to search for specific channels you want to retrieve. You can use any filters in a similar fashion with the sample code above.

A PublicGroupChannelListQuery instance provides many types of search filters such as ChannelNameContainsFilter and ChannelUrlsFilter. You can use these filters to search for specific public group channels.

The sample code below shows the query instance, which returns a list of the current user's group channels that partially match the specified keyword in the ChannelNameContainsFilter in the channels' name.

var listQuery = sb.GroupChannel.createPublicGroupChannelListQuery();
listQuery.includeEmpty = true;
listQuery.channelNameContainsFilter = 'Sendbird';

listQuery.next(function(groupChannels, error) {
    if (error) {
        // Handle error.
    }

    // Through "groupChannels" parameter of the callback function, which Sendbird server has passed a result list to,
    // a list of group channels that have 'Sendbird' in their names is returned.
    ...
});

The following shows the query instance, which returns a list of the current user's group channels that partially match the specified keyword in the ChannelUrlsFilter in the channels' URL.

var listQuery = sb.GroupChannel.createPublicGroupChannelListQuery();
listQuery.includeEmpty = true;
listQuery.channelUrlsFilter = ['seminar', 'lecture'];

listQuery.next(function(groupChannels, error) {
    if (error) {
        // Handle error.
    }

    // Through "groupChannels" parameter of the callback function, which Sendbird server has passed a result list to,
    // a list of group channels that have 'seminar' or 'lecture' in their URLs is returned.
    ...
});

The following table shows all supported filters for PublicGroupChannelListQuery to search for specific channels you want to retrieve. You can use any filters in a similar fashion with the sample code above.

public boolean isLoading()

const query = sb.createMessageSearchQuery("Sendbird", {
    channelUrl: '',
    channelCustomType: '',
    limit: 20,
    exactMatch: false,
    messageTimestampFrom: null,
    messageTimestampTo: null,
    order: 'score',
    reverse: false
});

query.next(function(messages, error) {
    if (error) {
        // Handle error.
    }

    ...
});

query.hasNext

query.isLoading

const params = new sb.FileMessageParams();
...
params.file = FILE;
params.fileName = FILE_NAME;
params.fileSize = FILE_SIZE;
params.mimeType = MIME_TYPE;
params.thumbnailSizes = [{maxWidth: 100, maxHeight: 100}, {maxWidth: 200, maxHeight: 200}]; // Add the maximum sizes of thumbnail images (allowed number of thumbnail images: 3).

groupChannel.sendFileMessage(params, function(fileMessage, error) {
    if (error) {
        // Handle error.
    }

    var thumbnailFirst = fileMessage.thumbnails[0];
    var thumbnailSecond = fileMessage.thumbnails[1];

    var maxHeightFirst = thumbnailFirst.maxHeight;      // 100
    var maxHeightSecond = thumbnailSecond.maxHeight;    // 200

    var urlFirst = thumbnailFirst.url;      // The URL of first thumbnail file.
    var urlSecond = thumbnailSecond.url;    // The URL of second thumbnail file.

    ...
});

const params = new sb.FileMessageParams();
params.file = FILE;
params.fileName = FILE_NAME;
params.customType = CUSTOM_TYPE;
params.data = DATA;
...

var sentFileMessage = groupChannel.sendFileMessage(params,
    function(event) {   // Check progress of file upload request.
        console.log(parseInt(Math.floor(event.loaded / event.total * 100)) + '%');
        // Display upload progress with UI component.
    },
    function(fileMessage, error) {  // Callback to execute when either a successful response or error data returns.
        if (error) {
            // Handle error.
        }

        ...
    }
);

const params = new sb.FileMessageParams();
params.file = FILE;
params.fileName = FILE_NAME;
params.customType = CUSTOM_TYPE;
params.data = DATA;

var sentFileMessage = groupChannel.sendFileMessage(params, function(fileMessage, error) {
    if (error) {
        // Handle error.
    }

    ...
});

// Cancel uploading a file in the file message.
var cancelResult = groupChannel.cancelUploadingFileMessage(sentFileMessage.reqId);
...

const params = new sb.UserMessageParams();
...
params.translationTargetLanguages = ['es', 'ko'];   // Spanish and Korean

groupChannel.sendUserMessage(params, function(userMessage, error) {
    if (error) {
        // Handle error.
    }

    ...
});

var channelHandler = new sb.ChannelHandler();

channelHandler.onMessageReceived = function(channel, message) {
    var esTranslatedMessage = message.translations['es'];   // Spanish
    ...
    // Display translation in UI.
};

sb.addChannelHandler(UNIQUE_HANDLER_ID, channelHandler);

const targetLanguages = ['es', 'de'];   // Spanish and German

// The USER_MESSAGE below indicates a UserMessage object which represents an already sent or received text message.
groupChannel.translateUserMessage(USER_MESSAGE, targetLanguages, function(userMessage, error) {
    if (error) {
        // Handle error.
    }

    var esTranslatedMessage = userMessage.translations['es'];   // Spanish
    var deTranslatedMessage = userMessage.translations['de'];   // German
    ...

    // Display translations in UI.
});