Pagination

List endpoints use offset pagination with page and limit query parameters. Chatway does not use cursor-based pagination (cursor, next_cursor, or has_more).

Query parameters

Parameter Type Default Description
page integer 1 Page number (1-based). Must be at least 1.
limit integer varies Number of records per page. Must be at least 1. Maximum depends on the endpoint (see below).

Example:

curl -G "https://developers.chatway.app/api/v1/contacts" \
  -H "X-API-KEY: your_api_key" \
  --data-urlencode "page=2" \
  --data-urlencode "limit=25"

Response shape

Paginated responses include data, meta.pagination, and links:

{
  "data": [],
  "meta": {
    "pagination": {
      "total": 42,
      "count": 10,
      "per_page": 10,
      "current_page": 2,
      "total_pages": 5
    }
  },
    "links": {
    "self": "https://developers.chatway.app/api/v1/contacts?page=2",
    "first": "https://developers.chatway.app/api/v1/contacts?page=1",
    "next": "https://developers.chatway.app/api/v1/contacts?page=3",
    "last": "https://developers.chatway.app/api/v1/contacts?page=5"
  }
}
Field Description
meta.pagination.total Total records across all pages
meta.pagination.count Records returned on this page
meta.pagination.per_page Page size used for this response (matches limit)
meta.pagination.current_page Current page number
meta.pagination.total_pages Total number of pages
links.next URL for the next page, or null on the last page
links.first / links.last First and last page URLs

Follow links.next until it is null, or increment page until current_page >= total_pages.

Defaults and limits by endpoint

Endpoint Default limit Maximum limit
GET /contacts 10 100
GET /conversations/all 10 100
GET /conversations/{id}/messages 20 20
GET /widgets 20 100
GET /agents 20 100

Sending limit above the maximum returns 422 with an validation error.

Sort order

Endpoint Order
GET /conversations/all Open conversations first, then by most recent message activity (newest first)
GET /conversations/{id}/messages Newest messages first (sort_number descending)
GET /contacts Platform default contact ordering for your workspace
GET /widgets Platform default widget ordering
GET /agents Platform default agent ordering

Sort order is not configurable through query parameters on these endpoints.

Live data and page drift

Pagination is a snapshot at request time.

For near-real-time workflows, prefer webhooks (message.received) instead of polling message or conversation lists on a short interval.

Field filtering

List endpoints also accept optional include_fields and exclude_fields query parameters (comma-separated). Invalid field names return 422. See each endpoint's schema in API Reference for allowed fields.

Related pages