Conventions

Pagination

Requests that contain multiple items will be paginated by default. Each page will provide a maximum of 20 items per page.

Two parameters can be used to control the number of items retrieved:

  • limit: The number of rows to be returned (maximum: 20, default: 20).
  • offset: The record number to start returning from (default: 0).

Most resources will provide these links at the end of the response object in a link array that supplies links with rel=next and rel=prev attributes.

This makes programmatic pagination easy as you can simply detect the presence of these attributes. You can loop through the pages until you receive a response of ‘No messages found’.

Note: For ease of use the following resources aren’t paginated:

  • Workspaces
  • Scenarios
  • Messages

Extra parameters

It’s also possible that the messages are older than the default filter that is applied. At present Whispir provides a default of the last 7 days of messages. You can ask for older messages by using the following 4 parameters:

  • criteriaFromDate (format: dd/mm/yyyy)
  • criteriaFromTime (format: hh:mm)
  • criteriaToDate (format: dd/mm/yyyy)
  • criteriaToTime (format: hh:mm)

All four parameters are required for a date search to work. Click here to see an example.

You can also use the parameter viewType=shared if the messages you're looking for were sent from other users (not the API user).

Case sensitivity of headers

As per RFC-2616 the headers in both the request and response are not case sensitive. Ensure that your integration takes this into account when interacting with the Whispir API.

  • JSON
  • XML

Pagination

Request for the first page of messages:

HTTP/1.1 GET https://api.<region>.whispir.com/?apikey=[your-api-key]&limit=20&offset=0

Request for the second page of messages (note that the offset is now 20):

HTTP/1.1 GET https://api.<region>.whispir.com/?apikey=[your-api-key]&limit=20&offset=20

Request for the page of messages that doesn't exist:

{{codeStart}}

HTTP/1.1 GET https://api.<region>.whispir.com/workspaces/7311ABEB701E7C60/messages?apikey=[your-api-key]&limit=20&offset=20

{

"status" : "No records found"

}

{{codeEnd}}

Request for records from 01/01/2019 00:00 to 01/07/2019 23:59:

https://api.<region>.whispir.com/messages?apikey=[your-api-key]&criteriaFromDate=01/01/2019&criteriaFromTime=00:00&criteriaToDate=01/07/2019&criteriaToTime=23:59