List All Chats

TypeScript

import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: '919876543210', // the phone to act with (x-phone)
});

async function main() {
  const response = await client.chats.listChats();
  console.log(response);
}

main();

{
  "from": 1,
  "to": 20,
  "count": 20,
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": null,
  "chats": [
    {
      "org_id": "00000000-0000-0000-0000-000000000000",
      "chat_id": "120363000000000000@g.us",
      "org_phone": "911111111111@c.us",
      "chat_name": "Example Group",
      "chat_type": "group",
      "chat_image": "https://example.com/images/example.jpg",
      "invite_link": "https://chat.whatsapp.com/invite/AAAAAAAAAAAAAAAAAAAAAA",
      "label_ids": {
        "label-aaaaaaaaaaaaaaaa": true
      },
      "labels": [
        "priority"
      ],
      "custom_properties": {
        "Custom Property": "Value"
      },
      "assigned_to": "user@example.com",
      "chat_access": {
        "user@example.com": true
      },
      "group_description": "A sample group description",
      "info_admins_only": false,
      "messages_admins_only": false,
      "add_members_admins_only": false,
      "member_count": 12,
      "members": {
        "key": {
          "org_id": "00000000-0000-0000-0000-000000000000",
          "chat_id": "120363000000000000@g.us",
          "org_phone": "911111111111@c.us",
          "contact_id": "922222222222@c.us",
          "contact_name": "John Doe",
          "contact_image": "https://example.com/images/example.jpg",
          "contact_color": "#000000",
          "is_admin": false,
          "is_super_admin": false,
          "is_internal": false
        }
      },
      "latest_message": {
        "message_id": "true_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAA",
        "org_id": "00000000-0000-0000-0000-000000000000",
        "org_phone": "911111111111@c.us",
        "chat_id": "120363000000000000@g.us",
        "body": "Hello! This is a sample message.",
        "message_type": "chat",
        "from_me": true,
        "author": "922222222222@c.us",
        "ack": "4",
        "timestamp": "2026-01-15T09:30:00+00:00",
        "media": {
          "path": "https://example.com/images/example.jpg",
          "mimetype": "image/png",
          "filename": "image.png"
        },
        "mentioned_ids": [
          "922222222222@c.us"
        ],
        "performed_by": "api",
        "quoted_message_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "sender_phone": "911111111111@c.us",
        "sent_message_id": "00000000-0000-0000-0000-000000000000",
        "delivery_info": {
          "delivered": {
            "key": null
          },
          "read": {
            "key": null
          },
          "pending": [],
          "read_count": null,
          "delivered_count": null
        },
        "is_deleted": null,
        "is_forwarded": null,
        "is_starred": null,
        "has_media": null,
        "unique_id": "AAAAAAAAAAAAAAAAAAAAAA",
        "updated_at": "2026-01-15T09:31:12.884+00:00"
      },
      "latest_message_timestamp": "2026-01-15T09:30:00+00:00",
      "message_unread_count": 0,
      "flag_count_map": {
        "key": null
      },
      "parent_community_id": null,
      "is_archived": false,
      "group_metadata": {},
      "is_muted": false,
      "is_exited": false,
      "closed_at": null,
      "created_at": "2026-01-10T08:00:00+00:00",
      "updated_at": "2026-01-15T09:30:00.025233+00:00"
    }
  ]
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

TypeScript

import { PeriskopeApi } from '@periskope/periskope-client';

const client = new PeriskopeApi({
  authToken: 'YOUR_API_KEY',
  phone: '919876543210', // the phone to act with (x-phone)
});

async function main() {
  const response = await client.chats.listChats();
  console.log(response);
}

main();

{
  "from": 1,
  "to": 20,
  "count": 20,
  "start_time": "2026-01-01T00:00:00Z",
  "end_time": null,
  "chats": [
    {
      "org_id": "00000000-0000-0000-0000-000000000000",
      "chat_id": "120363000000000000@g.us",
      "org_phone": "911111111111@c.us",
      "chat_name": "Example Group",
      "chat_type": "group",
      "chat_image": "https://example.com/images/example.jpg",
      "invite_link": "https://chat.whatsapp.com/invite/AAAAAAAAAAAAAAAAAAAAAA",
      "label_ids": {
        "label-aaaaaaaaaaaaaaaa": true
      },
      "labels": [
        "priority"
      ],
      "custom_properties": {
        "Custom Property": "Value"
      },
      "assigned_to": "user@example.com",
      "chat_access": {
        "user@example.com": true
      },
      "group_description": "A sample group description",
      "info_admins_only": false,
      "messages_admins_only": false,
      "add_members_admins_only": false,
      "member_count": 12,
      "members": {
        "key": {
          "org_id": "00000000-0000-0000-0000-000000000000",
          "chat_id": "120363000000000000@g.us",
          "org_phone": "911111111111@c.us",
          "contact_id": "922222222222@c.us",
          "contact_name": "John Doe",
          "contact_image": "https://example.com/images/example.jpg",
          "contact_color": "#000000",
          "is_admin": false,
          "is_super_admin": false,
          "is_internal": false
        }
      },
      "latest_message": {
        "message_id": "true_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAA",
        "org_id": "00000000-0000-0000-0000-000000000000",
        "org_phone": "911111111111@c.us",
        "chat_id": "120363000000000000@g.us",
        "body": "Hello! This is a sample message.",
        "message_type": "chat",
        "from_me": true,
        "author": "922222222222@c.us",
        "ack": "4",
        "timestamp": "2026-01-15T09:30:00+00:00",
        "media": {
          "path": "https://example.com/images/example.jpg",
          "mimetype": "image/png",
          "filename": "image.png"
        },
        "mentioned_ids": [
          "922222222222@c.us"
        ],
        "performed_by": "api",
        "quoted_message_id": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
        "sender_phone": "911111111111@c.us",
        "sent_message_id": "00000000-0000-0000-0000-000000000000",
        "delivery_info": {
          "delivered": {
            "key": null
          },
          "read": {
            "key": null
          },
          "pending": [],
          "read_count": null,
          "delivered_count": null
        },
        "is_deleted": null,
        "is_forwarded": null,
        "is_starred": null,
        "has_media": null,
        "unique_id": "AAAAAAAAAAAAAAAAAAAAAA",
        "updated_at": "2026-01-15T09:31:12.884+00:00"
      },
      "latest_message_timestamp": "2026-01-15T09:30:00+00:00",
      "message_unread_count": 0,
      "flag_count_map": {
        "key": null
      },
      "parent_community_id": null,
      "is_archived": false,
      "group_metadata": {},
      "is_muted": false,
      "is_exited": false,
      "closed_at": null,
      "created_at": "2026-01-10T08:00:00+00:00",
      "updated_at": "2026-01-15T09:30:00.025233+00:00"
    }
  ]
}

{
  "code": "UNAUTHORIZED_ERROR",
  "message": "Invalid bearer auth token",
  "status": 401
}

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 422,
  "fields": {
    "body.chat_id": {
      "message": "chat_id is required"
    }
  }
}

{
  "code": "RATE_LIMIT_ERROR",
  "message": "You can only make 100 requests per second",
  "status": 429
}

{
  "code": "UNKNOWN_ERROR",
  "message": "Internal server error",
  "status": 500
}

Authorizations

Authorization

string

header

required

Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.

Headers

x-phone

string

Optional. Scope results to a single phone: country code + number without symbols or spaces (e.g. 911111111111), or a phone_id (phone-xxxxxxxxxxxx). Omit to return data across all phones the API token can access.

Example:

"919876543210"

Query Parameters

offset

integer | null

Number of records to skip before the first returned record. Use together with limit to paginate: page N is offset = N * limit. Defaults to 0.

Required range: x >= 0

Example:

0

limit

integer

Maximum number of records to return in one page. Cannot exceed 2000. Defaults to 1000.

Required range: 1 <= x <= 2000

Example:

1000

start_time

string

Only return records at or after this time. Accepts ISO 8601 (e.g. 2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported. Compared at minute precision.

Example:

"2026-01-01T00:00:00Z"

end_time

string

Only return records at or before this time. Accepts ISO 8601 (e.g. 2026-01-01T00:00:00Z) and common date formats (YYYY-MM-DD, YYYY-MM-DD HH:mm, DD/MM/YYYY). Epoch timestamps are not supported. Compared at minute precision.

Example:

"2026-01-31T23:59:00Z"

string

Case-insensitive substring search across chat_id, chat_name, chat_type, label ids and custom property values. Composes with the other filters.

Example:

"Example Group"

chat_id

string

Return only chats with these exact chat_ids (including the @c.us / @g.us suffix). A single id or a comma-separated list — chats matching any listed id are returned.

Example:

"120363000000000000@g.us"

chat_type

string

Return only chats of these types: 'group', 'user' (1-1 with a regular account) or 'business' (1-1 with a business account). A single type or a comma-separated list — chats matching any listed type are returned.

Example:

"group"

label

string

Return only chats carrying these labels. Each entry is a label name (matched exactly, case-sensitive) or a label_id (label-xxxxxxxxxxxxxxxx); a single value or a comma-separated list — chats carrying any listed label are returned. A single unknown label name is ignored and returns unfiltered results; with multiple entries, every entry must exist or the request fails with a 422.

Example:

"priority"

sort_by

enum<string>

Field to sort by: 'created_at' or 'latest_message_timestamp'. Defaults to 'created_at'.

Available options:

created_at,

latest_message_timestamp

Example:

"latest_message_timestamp"

sort_order

string

Sort direction: 'asc' or 'desc' (case-insensitive). Defaults to 'desc'.

Example:

"desc"

Response

Paginated list of chats

from

integer

1-based index of the first record in this page (offset + 1).

Example:

1

integer

1-based index of the last record in this page.

Example:

20

count

integer

Number of records in this page — the length of the chats array, not the total across all pages.

Example:

20

start_time

string

Echo of the start_time filter, present only when it was sent.

Example:

"2026-01-01T00:00:00Z"

end_time

string

Echo of the end_time filter, present only when it was sent.

chats

object[]

The chats in this page.

Show child attributes

API

Chat APIs

Group Settings APIs

Message APIs

Scheduled Message APIs

Media APIs

Contact APIs

Ticket APIs

Custom Property APIs

Task APIs

Queue APIs

Phone APIs

Notes APIs

Reaction APIs

Knowledge Base APIs

Member APIs

AI APIs

Webhook APIs

Webhooks

Authorizations

Headers

Query Parameters

Response