> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # List All Chats > Returns a paginated list of chats, newest first. Filter by chat_id, chat_type, label or a created_at time window. ## OpenAPI ````yaml api-reference/openapi-generated.json GET /v1/chats openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/chats: get: tags: - Chats summary: List chats description: >- Returns a paginated list of chats, newest first. Filter by chat_id, chat_type, label or a created_at time window. operationId: listChats parameters: - schema: type: integer nullable: true minimum: 0 description: >- 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. example: 0 required: false description: >- 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. name: offset in: query - schema: type: integer minimum: 1 maximum: 2000 description: >- Maximum number of records to return in one page. Cannot exceed 2000. Defaults to 1000. example: 1000 required: false description: >- Maximum number of records to return in one page. Cannot exceed 2000. Defaults to 1000. name: limit in: query - schema: type: string description: >- 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' required: false description: >- 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. name: start_time in: query - schema: type: string description: >- 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' required: false description: >- 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. name: end_time in: query - schema: type: string description: >- 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 required: false description: >- Case-insensitive substring search across chat_id, chat_name, chat_type, label ids and custom property values. Composes with the other filters. name: q in: query - schema: type: string description: >- 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 required: false description: >- 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. name: chat_id in: query - schema: type: string description: >- 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 required: false description: >- 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. name: chat_type in: query - schema: type: string description: >- 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 required: false description: >- 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. name: label in: query - schema: type: string enum: - created_at - latest_message_timestamp description: >- Field to sort by: 'created_at' or 'latest_message_timestamp'. Defaults to 'created_at'. example: latest_message_timestamp required: false description: >- Field to sort by: 'created_at' or 'latest_message_timestamp'. Defaults to 'created_at'. name: sort_by in: query - schema: type: string description: >- Sort direction: 'asc' or 'desc' (case-insensitive). Defaults to 'desc'. example: desc required: false description: >- Sort direction: 'asc' or 'desc' (case-insensitive). Defaults to 'desc'. name: sort_order in: query - schema: type: string example: '919876543210' description: >- 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. required: false description: >- 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. name: x-phone in: header responses: '200': description: Paginated list of chats content: application/json: schema: type: object properties: from: type: integer description: >- 1-based index of the first record in this page (offset + 1). example: 1 to: type: integer description: 1-based index of the last record in this page. example: 20 count: type: integer description: >- Number of records in this page — the length of the `chats` array, not the total across all pages. example: 20 start_time: type: string description: >- Echo of the start_time filter, present only when it was sent. example: '2026-01-01T00:00:00Z' end_time: type: string description: >- Echo of the end_time filter, present only when it was sent. chats: type: array items: $ref: '#/components/schemas/Chat' description: The chats in this page. examples: default: summary: Response body value: 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' '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- 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(); - lang: bash label: cURL source: |- curl -X GET 'https://api.periskope.app/v1/chats' \ -H 'Authorization: Bearer YOUR_API_KEY' \ -H 'x-phone: 919876543210' components: schemas: Chat: type: object properties: org_id: type: string format: uuid description: >- The unique identifier of the organization that owns the WhatsApp account. example: 00000000-0000-0000-0000-000000000000 chat_id: type: string description: >- The unique identifier of the WhatsApp chat (format: {phone_number}@c.us for individual chats or {group_id}@g.us for groups). example: 120363000000000000@g.us org_phone: type: string description: >- The organization phone that the chat belongs to (in the format {phone_number}@c.us). example: 911111111111@c.us chat_name: type: string description: >- The display name of the chat. For groups, this is the group name. For individual chats, this is the contact's name. example: Example Group chat_type: type: string description: The type of chat. Can be `group`, `user`, or `business`. example: group chat_image: type: string description: The URL of the chat's profile image. example: https://example.com/images/example.jpg invite_link: type: string description: >- The invite link of the chat. Group chats only, and only when the phone is an admin. example: https://chat.whatsapp.com/invite/AAAAAAAAAAAAAAAAAAAAAA label_ids: type: object additionalProperties: type: boolean description: >- A map of label identifiers associated with the chat, where keys are label IDs and values are booleans. example: label-aaaaaaaaaaaaaaaa: true labels: type: array items: type: string description: An array of labels associated with the chat. example: - priority custom_properties: type: object description: >- A map of custom properties associated with the chat. Values depend on the property type: dropdown, text, date. example: Custom Property: Value assigned_to: type: string description: >- The email address of the user assigned to this chat. Absent when unassigned. example: user@example.com chat_access: type: object additionalProperties: type: boolean description: >- A map of user access permissions, where keys are email addresses and values are booleans. Absent when no per-chat overrides exist. example: user@example.com: true group_description: type: string description: The description text for group chats. Group chats only. example: A sample group description info_admins_only: type: boolean description: Indicates if only admins can modify group info. example: false messages_admins_only: type: boolean description: Indicates if only admins can send messages in the group. example: false add_members_admins_only: type: boolean description: Indicates if only admins can add new members to the group. example: false member_count: type: integer description: The total number of participants in the chat. example: 12 members: type: object additionalProperties: $ref: '#/components/schemas/GroupParticipant' description: >- A map of members in the chat, keyed by WhatsApp ID (format: {phone_number}@c.us). Only returned when fetching a single chat by id — list results omit it. latest_message: $ref: '#/components/schemas/ChatMessage' latest_message_timestamp: type: string description: >- Timestamp of the most recent message in the chat, as an ISO 8601 UTC timestamp. example: '2026-01-15T09:30:00+00:00' message_unread_count: type: integer description: The number of unread messages in the chat. example: 0 flag_count_map: type: object additionalProperties: type: number description: >- A map of flagged messages, where keys are phone numbers and values are flagged messages count. parent_community_id: type: string description: Indicates the id of the parent community for the group. is_archived: type: boolean description: Indicates if the chat has been archived. example: false group_metadata: type: object description: Additional raw group metadata synced from WhatsApp, when present is_muted: type: boolean description: Indicates if notifications for this chat are muted. example: false is_exited: type: boolean description: Indicates if the organization has left this chat. example: false closed_at: type: number description: >- The timestamp when the chat was closed, if applicable, as an epoch timestamp in milliseconds. Absent while the chat is open. created_at: type: string description: The ISO 8601 formatted timestamp when the chat was created. example: '2026-01-10T08:00:00+00:00' updated_at: type: string description: The ISO 8601 formatted timestamp when the chat was last updated. example: '2026-01-15T09:30:00.025233+00:00' description: >- A WhatsApp chat (1-1 conversation or group) synced into the workspace, together with its Periskope attributes (labels, assignee, custom properties, status). GroupParticipant: type: object properties: org_id: type: string format: uuid description: >- The unique identifier of the organization that owns the WhatsApp account. example: 00000000-0000-0000-0000-000000000000 chat_id: type: string description: The unique identifier of the WhatsApp chat. example: 120363000000000000@g.us org_phone: type: string description: >- The WhatsApp ID of the organization's account (format: {phone_number}@c.us). example: 911111111111@c.us contact_id: type: string description: 'The WhatsApp ID of the member (format: {phone_number}@c.us).' example: 922222222222@c.us contact_name: type: string description: The display name of the member. example: John Doe contact_image: type: string description: The URL of the member's profile image. example: https://example.com/images/example.jpg contact_color: type: string description: The hex color code assigned to the member in Periskope's UI. example: '#000000' is_admin: type: boolean description: Indicates if the member has admin privileges in the chat. example: false is_super_admin: type: boolean description: Indicates if the member has super admin privileges in the chat. example: false is_internal: type: boolean description: Indicates if the member is an internal user of the organization. example: false description: >- A participant of a chat, as returned inside the members map of a chat fetched by id. Combines the participant record with the matching contact (name, image, color). ChatMessage: type: object properties: message_id: type: string description: >- Unique id of the message, in the form __ example: true_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAAAA org_id: type: string format: uuid description: Id of the organization the message belongs to example: 00000000-0000-0000-0000-000000000000 org_phone: type: string description: >- Org phone (WhatsApp account) the message was sent or received on, as country code + number suffixed with @c.us example: 911111111111@c.us chat_id: type: string description: >- Chat the message belongs to — @c.us for 1-1 chats, @g.us for group chats example: 120363000000000000@g.us body: type: string description: Text content of the message, or the caption of a media message. example: Hello! This is a sample message. message_type: type: string description: >- Content type of the message: 'chat' for text, otherwise the media/attachment type (e.g. 'image', 'video', 'document', 'audio', 'ptt', 'sticker', 'location', 'poll_creation') example: chat from_me: type: boolean description: >- true when the message was sent by the org phone, false when it was received from the contact example: true author: type: string description: >- In group chats, the participant who sent the message (@c.us). example: 922222222222@c.us ack: type: string description: >- WhatsApp acknowledgement level of an outgoing message as a string: '1' sent, '2' delivered, '3' read, '4' played/read. example: '4' timestamp: type: string description: When the message was sent, as an ISO 8601 UTC timestamp example: '2026-01-15T09:30:00+00:00' media: type: object properties: path: type: string description: URL of the media file example: https://example.com/images/example.jpg mimetype: type: string description: MIME type of the media file example: image/png filename: type: string description: Filename of the media file, when applicable example: image.png description: >- Media attached to the message (may also carry dimensions, size, thumbnail). mentioned_ids: type: array items: type: string description: Contact ids @-mentioned in the message body. example: - 922222222222@c.us performed_by: type: string description: Member email or "api" when the message was sent through Periskope. example: api quoted_message_id: type: string description: >- message_id of the message this message replies to. Absent when the message is not a reply. example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA sender_phone: type: string description: >- Phone that sent the message, as country code + number suffixed with @c.us example: 911111111111@c.us sent_message_id: type: string description: >- Internal id assigned when the message was sent via the Periskope queue. Absent for received messages. example: 00000000-0000-0000-0000-000000000000 delivery_info: type: object properties: delivered: type: object additionalProperties: type: number description: Map of recipient contact_id to delivery epoch-ms timestamp read: type: object additionalProperties: type: number description: Map of recipient contact_id to read epoch-ms timestamp pending: type: array items: type: string description: Recipients the message has not been delivered to yet read_count: type: number description: Number of recipients who have read the message delivered_count: type: number description: Number of recipients the message was delivered to description: Per-recipient delivery and read receipts of an outgoing message. is_deleted: type: boolean description: true when the message was deleted for everyone. is_forwarded: type: boolean description: true when the message was forwarded. is_starred: type: boolean description: true when the message is starred. has_media: type: boolean description: true when the message carries media. unique_id: type: string description: >- WhatsApp message id without the from_me/chat_id prefix — accepted by message endpoints in place of the full message_id example: AAAAAAAAAAAAAAAAAAAAAA updated_at: type: string description: >- When the message record was last updated (e.g. by a delivery receipt), as an ISO 8601 UTC timestamp example: '2026-01-15T09:31:12.884+00:00' description: An object containing details about the latest message sent in the chat. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.