Message History

Ably’s message history feature allows clients to retrieve messages they missed during a brief disconnection. Using it as a primary database is an architectural anti-pattern that will lead to problems.

When a client disconnects, Ably automatically handles the reconnection. If the disconnection lasts less than 2 minutes, Ably’s connection-state recovery feature streams any missed messages to the client. For longer outages, the client must use the History API to fetch the missed messages.

Retrieve channel history

Use the history() method to retrieve previously published messages:

History parameters

Customize your history query with the following parameters:

Parameter	Description
start	Earliest time in milliseconds since the epoch for any messages retrieved
end	Latest time in milliseconds since the epoch for any messages retrieved
direction	forwards or backwards (default: backwards)
limit	Maximum number of messages to retrieve per page, up to 1,000 (default: 100)

Query by time range

Get messages in chronological order

Pagination

History results are paginated. Use the hasNext() and next() methods to iterate through pages:

Continuous history with rewind

Use the rewind channel option to get historical messages when attaching to a channel:

Rewind by time

You can also rewind by time interval:

History with untilAttach

Get continuous history up to the point of channel attachment:

Message retention

How long messages are stored depends on your channel rules:

Storage Type	Default	Maximum
Ephemeral	2 minutes	2 minutes
Persisted (Free)	24 hours	24 hours
Persisted (Paid)	72 hours	365 days

To enable longer retention, configure the “Persist all messages” channel rule.

Presence history

You can also retrieve historical presence events:

Best practices

Use history for catch-up only

History is designed for short-term catch-up, not as a primary data store:

Limit history queries

Be specific about what you need:

Use integrations for long-term storage

For long-term storage and complex queries, use integrations to send data to your own database:

• Store messages in your database via webhooks
• Use message queues for processing
• Enable data warehousing for analytics

Next steps

• Learn about message storage options
• Explore rewind channel option
• Set up integrations for long-term storage
• Understand connection recovery