Rewind

The rewind parameter allows you to specify, at the time of attaching to a channel, where to start the attachment from.

You can specify either:

• A given number of messages.
• A point in time in the past, as a time interval.

The parameter relates to the initial attachment of a connection to a channel, and expresses the intent to attach to the channel at a position, or a point in time, in the past (that is, effectively “rewinding” the channel for the purposes of the present attachment).

The rewind parameter is specified using channel parameters.

A rewind value that is a number n (eg rewind=1) is a request to attach to the channel at a position n messages before the present position. If the attachment is successful, and one or more messages exist on the channel prior to the present position, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

If fewer than the requested number of messages exists on the channel (including the case that there are no prior messages), then the available messages are sent; this does not constitute an error.

To subscribe to a channel, getting the most recent message if available:

JavaScriptNode.jsJavaSwiftC# .NET
JavaScript

var realtime = new Ably.Realtime('<loading API key, please wait>');
realtime.channels.get('sax-pan-boo', {
  params: {rewind: '1'}
}).subscribe(msg => console.log("Received message: ", msg));

API Key:
Demo Only
Copy
Copied!

A rewind value can also be a string that is a time interval specifier. Supported specifier values express an integral number of seconds (eg 15s) or minutes (eg 2m). If that attachment is successful, and one or more messages exist on the channel in the given time interval prior to the present time, then those messages will be delivered to the subscriber immediately after the attachment has completed, and before any subsequent messages that arise in real time.

If you wish to use a time interval rewind but additionally specify a limit on the number of messages to be returned, you can use the rewindLimit channel parameter. For example, to request up to 10 messages in a window 5m before the present time, specify a channel parameter string of rewind=5m&rewindLimit=10. If fewer than the requested number of messages exists on the channel in that interval (including the case that there are no messages), then the available messages are sent; this does not constitute an error.

To subscribe to a channel, getting the most recent message if available:

var querystring = 'v=1.2&channels=sax-pan-boo&rewind=1&key=<loading API key, please wait>';
var eventSource = new EventSource('https://realtime.ably.io/event-stream?' + querystring);

API Key:
Demo Only
Copy
Copied!

var mqtt = require('mqtt');
var options = {
  keepalive: 30,
  username: '{{API_KEY_NAME}}', /* API key's name */
  password: '{{API_KEY_SECRET}}', /* API key's secret */
  port: 8883
};
var client = mqtt.connect('mqtts:mqtt.ably.io', options);
client.on('connect', () => {
  client.subscribe('[?rewind=1]sax-pan-boo');
});
client.on('message', (topic, message) => {
  ...
});

Copy
Copied!

At most 100 messages will be sent in a rewind request. If the number of messages within the specified interval is greater than that limit, then only the most recent messages up to that limit are sent. The attachment succeeds, but truncation of the message backlog is indicated as a non-fatal error in the attachment response.

Rewind by time (rewind=30s) can only get messages at most 2 minutes old. So, if you specify rewind=3m, you will only get the last 2 minutes of history upon attaching. For now, it’s not possible to reach into persisted history using time-based parameters.

Rewind by a certain number of messages (rewind=20) is restricted by the channel’s persistence period. If you’ve not enabled persisted history, this will be 2 minutes. If you have persistence enabled, this will be 24 hours for free accounts, and 72 hours for paid accounts.

The channel position expressed by a rewind parameter only has an effect on an initial channel attachment. Any subsequent reattachment of the same channel on the same connection, in order to resume the connection, will attempt to resume with continuity from the point at which the connection dropped. (There are a few exceptions to this: in particular, client libraries earlier than v1.2 that have been disconnected for over two minutes, and all clients when using recover mode ; in both cases the previous attachment state is not preserved).

Any rewind parameter value that cannot be parsed either as a number or a time specifier will cause the attachment request to fail and return an error.

If you have enabled the persist last message channel rule on a channel, you can attach with rewind=1 to retrieve the last message. Note that only the last message can be stored long-term (up to a year), and persisting the last message does not work for presence messages.

View the Channel Options API Reference.