rewind channel option enables a client to specify where to start an attachment from, when attaching to a channel. Rewind can provide context to clients attaching to a channel by passing them previously published messages, such as in the example of a joining a chat room.
Clients can rewind to a point in time in the past, or for a given number of messages.
Rewind 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, such as clients using
recover mode, where the previous attachment state is not preserved.
rewind property of
params can be set at a point in time in the past, or for a given number of messages.
rewind can also be set by qualifying a channel name during a call to
get(). For example, if you want to subscribe to channel
my_channel and fetch the most recent message, you would specify the channel as
[?rewind=1]my_channel. If the channel also contains metadata, you would apply rewind with
rewind value that is a number,
N, is a request to attach to the channel at a position
N messages before the present position. A
rewind value with a time specifier is a request to attach to the channel at a point in time in the past, such as
10s for 10 seconds, or
5m for 5 minutes.
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.
rewind value that cannot be parsed either as a number or a time specifier will cause the attachment request to fail and return an error.
The following example subscribes to a channel and retrieves the most recent message sent on it, if available:
rewind to an integer to retrieve a given number of messages in the past. If fewer than the requested number of messages exists on the channel, including the case where there are no prior messages, then any available messages are sent. This does not constitute an error.
The following is an example of qualifying the channel name to rewind by 1 message:
rewind to an integer with a time specifier to retrieve messages from a period of time in the past. The available time specifiers are are
s for seconds and
m for minutes, for example
The following is an example of qualifying the channel name to rewind by 10 seconds:
It is also possible to rewind by a set number of messages, within a period of time using the
For example, to request up to 10 messages in a window 5 minutes before the present time, specify a value of
rewind=5m&rewindLimit=10. If fewer than the requested number of messages exists on the channel, including the case where there are no prior messages, then any available messages are sent. This does not constitute an error.
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 is restricted by the channel’s persistence period. If persisted history, isn’t enabled for the channel then this will be 2 minutes. If you have persistence enabled, this will be 24 hours for free accounts, and 72 hours for paid accounts. As an example, if you specify
rewind=3m without persisted history enabled, you will only receive the last 2 minutes of messages upon attaching.