Warning: You are viewing an old version (1.0) of this documentation. We recommend you view the latest version 1.2.
REST Client Library API

History

The REST client library provides message and presence event history for channels. Channel history combines both instantaneous “live” history as well as the longer term persisted history. If persisted history is enabled for the channel, then messages will typically be stored for 24 – 72 hours on disk. If persisted history is not enabled, Ably retains the last two minutes of instantaneous “live” message history in memory.

Getting started

The Ably REST client library provides a straightforward API to retrieve paginated message or presence event history. Each page of history, by default, contains up to 100 messages. Message ordering, by default, is from most recent to oldest.

var rest = new Ably.Rest('xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU');
var channel = rest.channels.get('win-rub-egg');
channel.publish('example', 'message data', function(err) {
  channel.history(function(err, resultPage) {
    var recentMessage = resultPage.items[0];
    alert('Most recent message: ' + recentMessage.id + ' - ' + recentMessage.data);
  });
});
var rest = new Ably.Rest('xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU');
var channel = rest.channels.get('win-rub-egg');
channel.publish('example', 'message data', function(err) {
  channel.history(function(err, resultPage) {
    var recentMessage = resultPage.items[0];
    console.log('Most recent message: ' + recentMessage.id + ' - ' + recentMessage.data);
  });
});
rest = Ably::Rest.new('xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU')
channel = rest.channels.get('win-rub-egg')
channel.publish 'example', 'message data'
result_page = channel.history
recent_message = result_page.items.first
puts "Most recent message: #{recent_message.message.id} - #{recent_message.data}")
rest = AblyRest('xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU')
channel = rest.channels.get('win-rub-egg')
result_page = channel.history()
recent_message = result_page.items[0]
print('Most recent message: ' + str(recent_message.message.id) + ' - ' + recent_message.data)
$rest = new Ably\AblyRest('xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU');
$channel = $rest->channels->get('win-rub-egg');
$channel->publish('example', 'message data');
$resultPage = $channel->history();
$recentMessage = $resultPage->items[0];
echo("Most recent message data: " . $recentMessage->data);
AblyRest rest = new AblyRest("xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU");
Channel channel = rest.channels.get("win-rub-egg");
channel.publish("example", "message data")
PaginatedResult<Message> resultPage = channel.history(null);
Message recentMessage = resultPage.items[0];
System.out.println("Most recent message: " + recentMessage.id + " - " + recentMessage.data);
AblyRest rest = new AblyRest("xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU");
IRestChannel channel = rest.Channels.Get("win-rub-egg");
await channel.PublishAsync("example", "message data");
PaginatedResult<Message> resultPage = await channel.HistoryAsync();
Message recentMessage = resultPage.Items[0];
Console.WriteLine("Most recent message: " + recentMessage.Id + " - " + recentMessage.Data);
ARTRest *rest = [[ARTRest alloc] initWithKey:@"xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU"];
ARTRestChannel *channel = [rest.channels get:@"win-rub-egg"];
[channel publish:@"example" data:@"message data"];
[channel history:^(ARTPaginatedResult<ARTMessage *> *resultPage, ARTErrorInfo *error) {
    ARTMessage *recentMessage = resultPage.items[0];
    NSLog(@"Most recent message: %@ - %@", recentMessage.id, recentMessage.data);
}];
let rest = ARTRest(key: "xVLyHw.p2MSDg:4eDsAjhrn1JdjApMEqXgtzp5q9gJ4DDzSj4WMpxdweU")
let channel = rest.channels.get("win-rub-egg")
channel.publish("example", data: "message data")
channel.history { resultPage, error in
    let recentMessage = resultPage!.items[0] as! ARTMessage
    print("Most recent message: \(recentMessage.id) - \(recentMessage.data)")
}

If you would prefer to just dive into code and see some examples of how to use history via the REST API, then we recommend you take a look at our REST tutorials.

Channel & Presence history

Both the Channel and Presence objects provide history. The Channel object provides the history of Message objects published on the channel, whereas the Presence object provides presence event history of that channel i.e. members entering, updating or leaving the channel as PresenceMessage objects.

Enabling persistent history

By default, persisted history on channels is disabled and messages are only stored by the Ably service for two minutes in memory. If persisted history is enabled for the channel, then messages will typically be stored for 24 – 72 hours on disk.

Every message that is persisted to or retrieved from disk counts as an extra message towards your monthly quote. For example, for a channel that has persistence enabled, if a message is published, two messages will be deducted from your monthly quota. If the message is later retrieved from history, another message will be deducted from your monthly quota.

To enable history on a channel, it is necessary to add a channel rule in the settings of your application dashboard. See the documentation on channel rules for further information on what they are and how to configure them.

API Reference

View the History API Reference.


Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.