Message history

The history feature enables users to retrieve messages that have been previously sent in a room. Message persistence is enabled by default for all chat rooms, with messages stored for 30 days. You can extend this retention period up to 365 days by contacting us.

Retrieve previously sent messages

Use the messages.history() method to retrieve messages that have been previously sent to a room. This returns a paginated response, which can be queried further to retrieve the next set of messages.

const historicalMessages = await room.messages.history({ orderBy: OrderBy.NewestFirst, limit: 50 });
console.log(historicalMessages.items);

if (historicalMessages.hasNext()) {
  const next = await historicalMessages.next();
  console.log(next);
} else {
  console.log('End of messages');
}

The following optional parameters can be passed when retrieving previously sent messages:

Understanding message ordering

The orderBy parameter determines the messages retrieved and their return order:

For the majority of chat UIs, the default behavior of newestFirst will be correct. This retrieves messages from most recent to oldest, which you can then reverse to display the newest message at the bottom of the UI.

Retrieve messages sent prior to subscribing

Retrieve historical messages sent before subscribing using historyBeforeSubscribe(). Messages are returned in order, from the most recent to the oldest (newestFirst). This is useful for providing conversational context when a user joins or rejoins a room, ensuring continuous message history without overlap.

Use the historyBeforeSubscribe() function returned as part of a message subscription response to only retrieve messages that were received before the listener was subscribed to the room. This returns a paginated response, which can be queried further to retrieve the next set of messages.

const { historyBeforeSubscribe } = room.messages.subscribe(() => {
  console.log('New message received');
});

const historicalMessages = await historyBeforeSubscribe({ limit: 50 });
console.log(historicalMessages.items);
if (historicalMessages.hasNext()) {
  const next = await historicalMessages.next();
  console.log(next);
} else {
  console.log('End of messages');
}

The following optional parameters can be passed when retrieving messages before subscribing: