Some endpoints can return a lot of results, such as hundreds of conversations or thousands of messages. Instead of sending everything at once, these endpoints return results in smaller groups called pages. You ask for one page at a time and keep asking until you have everything you need.Which endpoints use pages#
| Endpoint | Uses pages? | How |
|---|
| Get Inbox Data | Yes | start_from and limit |
| Get Thread Details | Yes | offset and limit |
| Get Whatsapp Templates | No | Returns all your templates in one response |
| All other endpoints | No | Return a single item or a short list |
Get Inbox Data and Get Thread Details work slightly differently. Read the section for the endpoint you're using. In particular, start_from counts from 1, while offset counts from 0.
Get Inbox Data#
Get Inbox Data returns your conversations, with the most recently active first.Settings#
You add these to the end of the web address, after a ?:| Setting | Required? | What it does |
|---|
start_from | Yes | The position of the first conversation you want. The first conversation is 1. |
limit | Yes | How many conversations to return, from 1 to 200. |
last_activity_after | Yes | Only include conversations with activity after this date and time, for example 2020-01-01T00:00:00Z. To get all conversations, use a date from before you started using Chronox. |
flag_active | No | Set to true to include only active conversations: those currently assigned to a team member, or with recent activity that haven't been archived. |
If you ask for more than 200, you'll get 200. If you set start_from or limit below 1, the API uses 1 instead.
Example#
This request asks for the first 50 conversations:The conversations are in data, and stats tells you where you are:{
"status": true,
"data": [
{ "…": "one conversation" }
],
"stats": {
"total_records": 132,
"start_from": 1,
"limit": 50
}
}
| Field | What it means |
|---|
stats.total_records | The total number of conversations that match your settings, across all pages. |
stats.start_from | The position this page started at. |
stats.limit | The page size that was used. |
Getting the next page#
Add limit to start_from to get the next page. With a limit of 50:| Page | start_from | Conversations |
|---|
| 1 | 1 | 1–50 |
| 2 | 51 | 51–100 |
| 3 | 101 | 101–150 |
You've reached the last page when start_from + limit is more than total_records, or when data is empty.If something's missing#
If start_from, limit or last_activity_after is missing or invalid, the request fails with one of these messages:Missing required fields: start_from, limit, and last_activity_after are required
Invalid start_from or limit values
Invalid last_activity_after date format
Get Thread Details#
Get Thread Details returns the messages in one conversation, with the newest first.Settings#
| Setting | Required? | What it does |
|---|
offset | No | How many messages to skip. The first message is at 0. Defaults to 0. |
limit | No | How many messages to return. Defaults to 50. |
There's no maximum limit, but very large pages are slow. Keep to 50–100 messages per page.
Example#
This request asks for the 50 newest messages in a conversation:The messages are in data.thread_execution_data, and data.pagination tells you where you are:{
"status": true,
"data": {
"thread_execution_data": [
{ "…": "one message" }
],
"pagination": {
"offset": 0,
"limit": 50,
"total_records": 318
}
}
}
Getting the next page#
Add limit to offset to get the next page. With a limit of 50:| Page | offset | Messages |
|---|
| 1 | 0 | 1–50 (newest) |
| 2 | 50 | 51–100 |
| 3 | 100 | 101–150 |
You've reached the last page when offset + limit is equal to or more than total_records, or when thread_execution_data is empty.If something's wrong#
If limit is 0 or less, or offset is below 0, the API responds with HTTP status 400 and one of these messages:Limit must be greater than 0
Offset must be greater than or equal to 0
When results change while you're reading them#
Both endpoints sort results by time, so new activity can move results between pages while you're reading them:In Get Inbox Data, a conversation that gets a new message moves to the top. As you go through the pages, you may see a conversation twice or miss one.
In Get Thread Details, a new message pushes older messages one place further back. The first message of your next page may be one you've already seen.
What this page doesn't cover#
Filtering. Get Inbox Data has more filters, such as by channel or assigned team member. See the Get Inbox Data endpoint page.
Rate limits. Reading many pages quickly counts towards your limit. See Rate limiting. 