History v2 (legacy) introduction

This is not the latest version of this API. Use Message Persistence instead.

General​

This function fetches historical messages of a channel. It is possible to control how messages are returned and in what order, for example you can:

  • Search for messages starting on the newest end of the timeline (default behavior - reverse = false)
  • Search for messages from the oldest end of the timeline by setting reverse to true.
  • Page through results by providing a start OR end timetoken.
  • Retrieve a slice of the time line by providing both a start AND end timetoken.
  • Limit the number of messages to a specific quantity using the count parameter.

Success Responses​

  • Array Element 0 – Array – Contains an array of JSON messages. Array will be between 0 and 100 in length, based on the count parameter (default 100) used at request time, and the number of valid messages available for the given time-slice.
  • Array Element 1 – Int – Start Timetoken of returned results,
  • Array Element 2 – Int – End Timetoken of returned results, Successful (HTTP Status 200) History() calls will always return a three-element array similar to:
[ [MSG1, MSG2, ...], START_TIMETOKEN, END_TIMETOKEN ]

for example: ["Pub1","Pub2","Pub3"],13406746729185766,13406746780720711]

Error Responses​

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

Paging​

Page through History v2, traversing newest to oldest: Perform the initial history request, without any start or end parameters (we'll limit results to two at a time to make this example easier to grok):

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4"

# returns
[["msg4","msg5","msg6","msg7"],14382111171320896,14382111251236844]

Using the start Timetoken provided from the last response, use as the start parameter for the next page:

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&start=14382111171320896"

# returns
[["msg1","msg2","msg3"],14382102111436851,14382102175496790]

Repeat, until you get 0 (zero) back as a start Timetoken. This indicates you are at the end of the list.

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&start=14382102111436851"

# returns
[[],0,0]