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.

Every message is redundantly stored across multiple isolated datacenters before acknowledgment, ensuring your chat history is always available when you need it.

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:

Parameter	Description	Default
start	Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned.	Earliest available message
end	Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned.	Current time
orderBy	The order in which to retrieve messages from; either oldestFirst or newestFirst.	newestFirst
limit	Maximum number of messages to be retrieved per page, up to 1,000.	100

Understanding message ordering

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

Order	Retrieves	Returns	Use case
newestFirst (default)	Most recent messages	[newest, ..., oldest]	Standard chat application
oldestFirst	Oldest messages from room start	[oldest, ..., newest]	Archives, exports, admin tools

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:

Parameter	Description	Default
start	Earliest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp equal to, or greater than, this value will be returned.	Earliest available message
end	Latest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned.	Current time
limit	Maximum number of messages to be retrieved per page, up to 1,000.	100