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

Example: request page 2 of a workspace with 3 contacts, 2 per page, returning only name and email:

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

Response shape

Paginated responses include data, meta.pagination, and links. Page 2 is the last page here, so it holds the remaining contact and links.next is null:

{
  "data": [
    {
      "type": "chat-contacts",
      "id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
      "attributes": {
        "name": "Jane Doe",
        "email": "jane@example.com"
      }
    }
  ],
  "meta": {
    "pagination": {
      "total": 3,
      "count": 1,
      "per_page": 2,
      "current_page": 2,
      "total_pages": 2
    }
  },
  "links": {
    "self": "https://developers.chatway.app/api/v1/contacts?page=2",
    "first": "https://developers.chatway.app/api/v1/contacts?page=1",
    "next": null,
    "last": "https://developers.chatway.app/api/v1/contacts?page=2"
  }
}

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

Pagination links contain only the page parameter. When following a pagination link, preserve the limit, include_fields and exclude_fields values from your original request if they are not included in that link.

Defaults and limits by endpoint

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

Sort order

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

Live data and page drift

Each page reflects the data when that request runs. A sequence of page requests is not one fixed snapshot. New messages can move conversations between pages, so a long-running scan can encounter a record more than once or miss a record that moved.

• Conversation lists can change order when new messages arrive, because ordering uses latest activity.
• Message lists can gain new rows while you paginate; a new visitor or agent message may appear on page 1 after you already fetched page 2.

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

When importing several pages, track records by their IDs rather than their position in the list. Keep the same page size and filters throughout the scan. Use webhooks for ongoing changes instead of repeatedly scanning the full history.

Field filtering

List Chat Contacts, List Conversations and List Conversation Messages support include_fields and exclude_fields. Supply comma-separated attribute names from that operation's allowed list. For example, include_fields=name,email requests those contact attributes. If both parameters are present, include_fields takes precedence. Invalid field names return 422. List Agents and List Widgets do not document field filtering.

Related pages

• Overview: authentication and resource summary
• Errors: validation and rate-limit responses
• Rate limits: request quotas per API key