Skip to main content
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:
ParameterDescriptionDefault
startEarliest 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
endLatest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned.Current time
orderByThe order in which to retrieve messages from; either oldestFirst or newestFirst.newestFirst
limitMaximum 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:
OrderRetrievesReturnsUse case
newestFirst (default)Most recent messages[newest, ..., oldest]Standard chat application
oldestFirstOldest 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:
ParameterDescriptionDefault
startEarliest 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
endLatest time to retrieve messages from, as a unix timestamp in milliseconds. Messages with a timestamp less than this value will be returned.Current time
limitMaximum number of messages to be retrieved per page, up to 1,000.100

Build docs developers (and LLMs) love

Get started for freeTalk to us