Message collection

A MessageCollection instance allows you to create a chat view that includes all up-to-date data. This page explains how to make a view using the collection.

First, create a MessageCollection instance. Here, you need to set a MessageListParams instance to determine the message order and the starting point of the message list in the chat view.

final collection = MessageCollection(
  channel: channel,
  params: MessageListParams(),
  handler: MyMessageCollectionHandler(),
  startingPoint: STARTING_POINT,
);

class MyMessageCollectionHandler extends MessageCollectionHandler {
  @override
  void onMessagesAdded(MessageContext context, GroupChannel channel, List<BaseMessage> messages) {
    // Update widgets with collection.messageList.
  }
  @override
  void onMessagesUpdated(MessageContext context, GroupChannel channel, List<BaseMessage> messages) {
    // Update widgets with collection.messageList.
  }
  @override
  void onMessagesDeleted(MessageContext context, GroupChannel channel, List<BaseMessage> messages) {
    // Update widgets with collection.messageList.
  }
  @override
  void onChannelUpdated(ChannelContext context, GroupChannel channel) {
    // Update widgets with collection.messageList.
  }
  @override
  void onChannelDeleted(ChannelContext context, String deletedChannelUrl) {
    // Back to the previous page.
  }
  @override
  void onHugeGapDetected() {
    // The Chat SDK detects that more than 300 messages are missing.
    collection.dispose();        // Dispose the collection.
    createMessageCollection();   // Create a new message collection object.
    // An additional implementation is required for initialization.
  }
}

The reference point for message retrieval in a chat view is startingPoint. This should be specified as a timestamp.

By default, startingPoint is set to SendbirdChat.maxInt, displaying the most recent messages first. However, if the startingPoint is set to the message last read by the user, it will display messages from where the user last read.

After creating a MessageCollection instance, initialize the instance through the initialize() method.

try {
  // Initialize messages from the startingPoint.
  await collection.initialize();
  // Messages are retrieved through API calls from the Sendbird server.
} catch (e) {
  // Handle error.
}

Use the loadPrevious() and loadNext() methods to retrieve messages from the previous page and the next page.

When the loadPrevious() method is called, the Chat SDK first checks whether there're messages to load from the previous page through hasPrevious. The same goes for hasNext and loadNext().

These methods have to be called during initialization as well.

try {
  // Load the previous messages
  // when the scroll reaches the first message in the chat view.
  if (collection.hasPrevious) {
      await collection.loadPrevious();
  }
} catch (e) {
  // Handle error.
}

Use MessageCollectionHandler to determine how the client app reacts to message-related events.

The following table shows possible cases where each event handler can be called.

A gap can be created for many reasons, such as when a user has been offline for days. When the client app comes back online, the Chat SDK checks with the Sendbird server to see if there are any new messages. If it detects that more than 300 messages are missing in the local cache compared to the Sendbird server, the SDK determines that there is a huge gap and onHugeGapDetected() is called.

Note: To adjust the number of missing messages that result in a call for onHugeGapDetected(), contact our support team.

In this case, the existing MessageCollection instance should be cleared through the dispose() method and a new one must be created for better performance.

collection.dispose();

The dispose() should be called when you destroy the chat screen to notify the SDK that this collection is no longer visible.

For example, this should be used when the current user exits from the chat screen.

collection.dispose();

// For the failed messages in MessageCollection
final failedMessages = await collection.getFailedMessages();
await collection.removeFailedMessages(failedMessages);
await collection.removeAllFailedMessages();