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();curl -X GET 'https://api.periskope.app/v1/chats' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210'{
"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
}Chat APIs
List All Chats
Returns a paginated list of chats, newest first. Filter by chat_id, chat_type, label or a created_at time window.
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();curl -X GET 'https://api.periskope.app/v1/chats' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'x-phone: 919876543210'{
"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
Headers
Query Parameters
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"
Response
Paginated list of chats
Was this page helpful?