List Chat Contacts

Retrieve a paginated list of chat contacts. When in mock mode, returns sample contact data.

GET https://developers.chatway.app/api/v1/contacts

Example request

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

Parameters

Name	In	Required	Type	Description
`search`	query	No	string\|null
`limit`	query	No	integer\|null
`page`	query	No	integer\|null
`include_fields`	query	No	string\|null	Allowed: widget_name, widget_id, team_id, name, email, phone, country_dialing_code, bgcolor, location, browser_type, country_code, country, country_flag, country_emoji, page_visited, online_status, last_active_at, blocked_at, is_name_updated, created_at, verified_id, verified_email, timezone, language, ip, operating_system. Example: `name,widget_name`. If both this and exclude_fields are sent, only include_fields is applied.
`exclude_fields`	query	No	string\|null	Allowed: widget_name, widget_id, team_id, name, email, phone, country_dialing_code, bgcolor, location, browser_type, country_code, country, country_flag, country_emoji, page_visited, online_status, last_active_at, blocked_at, is_name_updated, created_at, verified_id, verified_email, timezone, language, ip, operating_system. Ignored when include_fields is also present (include takes precedence).

Responses

200

application/json

data (array<object>, required)
- type (string, required)
- id (string, required)
- attributes (object, required)
  - widget_name (string|null, required)
  - widget_id (string|null, required)
  - team_id (string|null, required)
  - name (string|null, required)
  - email (string|null, required)
  - phone (string|null, required)
  - country_dialing_code (string|null, required)
  - bgcolor (string|null, required)
  - location (string|null, required)
  - browser_type (string|null, required)
  - country_code (string|null, required)
  - country (string|null, required)
  - country_flag (string|null, required)
  - country_emoji (string|null, required)
  - page_visited (array, required)
  - timezone (string|null, required)
  - language (string|null, required)
  - ip (string|null, required)
  - operating_system (string|null, required)
  - online_status (string|null, required)
  - last_active_at (string|null, required)
  - blocked_at (string|null, required)
  - is_name_updated (boolean, required)
  - created_at (string|null, required)
  - verified_id (string|null, required)
  - verified_email (string|null, required)
meta (object, required)
- pagination (object, required)
  - total (integer, required)
  - count (integer, required)
  - per_page (integer, required)
  - current_page (integer, required)
  - total_pages (integer, required)
links (object, required)
- self (string, required)
- first (string, required)
- next (string|null, required)
- last (string, required)

422

Pagination

Paginated list responses include data, meta.pagination, and links. Use the page and limit query parameters to walk results. Follow links.next until it is null, or increment page until current_page >= total_pages.

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 (1-based)
`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

Examples

Response 200 example

{
    "data": [
        {
            "type": "chat-contacts",
            "id": "9b0c5fe6-35ad-459d-b6ba-4288191f84f1",
            "attributes": {
                "widget_name": "Main site widget",
                "widget_id": "eouqtiupanm6uvglwshy",
                "team_id": "MOCK_TEAM_ID",
                "name": "John Doe",
                "email": "[email protected]",
                "phone": "+1XXXXXXXXXX",
                "country_dialing_code": "+1",
                "bgcolor": "#007F3E",
                "location": "New York, US",
                "browser_type": "Chrome 143",
                "country_code": "US",
                "country": "United States",
                "country_flag": "country flag",
                "country_emoji": "country emoji",
                "page_visited": [],
                "timezone": "timezone",
                "language": "language",
                "ip": "ip",
                "operating_system": "operating system",
                "online_status": "online",
                "last_active_at": "2026-02-04T10:30:00Z",
                "blocked_at": "blocked at",
                "is_name_updated": false,
                "created_at": "2026-02-04T10:30:00Z",
                "verified_id": "verified id",
                "verified_email": "verified email"
            }
        }
    ],
    "meta": {
        "pagination": {
            "total": 10,
            "count": 10,
            "per_page": 10,
            "current_page": 1,
            "total_pages": 1
        }
    },
    "links": {
        "self": "self",
        "first": "first",
        "next": "next",
        "last": "last"
    }
}