> ## Documentation Index > Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # List Chats > Get full or filtered list of all chats in the workspace. Supports filtering by label, WhatsApp account, phone, responsible, and more. ## OpenAPI ````yaml get /chats openapi: 3.0.3 info: title: Timelines Public API description: > # Timelines Public API _Some API calls may utilize message sending quota or be subject to message sending rate limits as described below._ ### Credit Utilization - Sending a message via API consumes 1 credit from message sending quota. - Sending a message with non-empty text and attachment consumes 2 credits from message sending quota. - If a message cannot be sent (invalid or not connected to WhatsApp number, WhatsApp server error), message sending quota will be restored (usually within a couple of hours). ### Message sending rate - Messages will be sent with random delay of about 2 seconds between each two messages (to avoid WhatsApp spam detection mechanisms). Contact support@timelines.ai if you want to modify delay for your workspace (available on Business plan only). - If you exceed message sending frequency, messages be queued and sent out with delay. Each queued message will consume a message sending credit, so the number of queued messages cannot exceed the available quota. ### Authorization: - Copy API token from [Public API page](https://app.timelines.ai/integrations/api/) in your TimelinesAI account. - Put the token in *Authorization* header of request as follows: ``` Authorization: Bearer 4d2d0239-e28c-4f4a-8a4d-3a3ca40056b8 ``` ### Message formatting: - use "\n" for line breaks version: 1.3.0 servers: - url: /integrations/api description: Public API root URL security: - bearerAuth: [] paths: /chats: get: summary: Get full or filtered list of all chats in the Workspace. description: >- Leave filtering parameters empty to get the unfiltered list. When multiple filtering parameters are specified, logical AND operation is applied. The result is paginated, page size is 50 records. The result is ordered first by the timestamp of the most recent message in a chat (descending), then by the name of the chat (alphabetically, ascending). parameters: - in: query name: label schema: type: string description: >- filters chats having at least one of specified labels (comma-separated) example: customer1,customer2,customer3 - in: query name: whatsapp_account_id schema: type: string description: >- filters chats belonging to one of the specified WhatsApp accounts (in wid format, comma-separated) example: 972501111111@s.whatsapp.net,972502222222@s.whatsapp.net - in: query name: group schema: type: boolean description: >- filters chats that are either group chats (true) or direct chats (false) - in: query name: responsible schema: type: string description: >- filters chats assigned to specific users (denoted by email address, comma-separated) example: john.doe@acme.com,anna.smith@acme.com - in: query name: name schema: type: string description: >- filter chats that contain any of specified strings (case-insensitive, comma-separated). Note: a string containing a whitespace will be matched as exact substring without being split to words. example: acme sales,contacts - in: query name: phone schema: type: string description: >- Filter direct (non-group) chats by a single phone number. Phone is sanitized in the same way as for sending messages. If sanitized value starts with '+', the match is exact. Otherwise, leading zeroes are removed and the number is matched as a substring of the stored phone. Group chats are always excluded when this parameter is used. example: '0501111111' - in: query name: read schema: type: boolean description: filter chats that are either read (true) or unread (false) - in: query name: closed schema: type: boolean description: filter chats that are either closed (true) or open (false) - in: query name: chatgpt_autoresponse_enabled schema: type: boolean description: >- filter chats where chatgpt auto-response is enabled (true) or disabled (false) - in: query name: page schema: type: integer description: >- specify the page of results (each page contains up to 50 items), starting with 1. Check \"has more page" response value to see if more pages are available. example: 1 - in: query name: created_after schema: type: string format: date-time description: >- filter chats that were created after this timestamp, can be specified with created_before example: '2024-12-31T23:59:59Z' - in: query name: created_before schema: type: string format: date-time description: >- filter chats that were created before this timestamp, can be specified with created_after example: '2024-12-31T23:59:59Z' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ChatListResponse' '400': $ref: '#/components/responses/BadRequestError' '401': $ref: '#/components/responses/UnauthorizedError' '403': $ref: '#/components/responses/AccessDenied' '404': $ref: '#/components/responses/NotFound' components: schemas: ChatListResponse: type: object required: - status - data properties: status: type: string example: ok enum: - ok - error data: type: object properties: has_more_pages: type: boolean chats: type: array items: $ref: '#/components/schemas/ChatInfo' ChatInfo: type: object required: - id - name - jid - is_group - closed - read - labels - chatgpt_autoresponse_enabled - whatsapp_account_id - chat_url - created_timestamp - unattended - photo properties: id: example: '1000001' type: integer name: example: John Doe type: string phone: example: '+972501111111' type: string description: > Contact's phone number in international format. `null` for group chats. jid: example: 14840000000@s.whatsapp.net type: string description: > WhatsApp-native identifier for the contact or group, structured as `@` — e.g. `14840000000@s.whatsapp.net` for a contact (the `id` part is the phone number) or `@g.us` for a group. Use this value with JID-addressed endpoints. is_group: example: false type: boolean closed: example: false type: boolean read: example: true type: boolean labels: example: - label1 - label2 - label3 type: array items: type: string chatgpt_autoresponse_enabled: type: boolean example: true description: >- Whether the AI Agent (ChatGPT autoresponse) is currently enabled for this chat. responsible_email: example: kate.smitch@acme.com type: string description: > Registration email of the team member responsible for the chat; `null` if the chat is unassigned. responsible_name: example: Kate Smith type: string whatsapp_account_id: example: 972502222222@s.whatsapp.net type: string chat_url: example: https://app.timelines.ai/chat/1000001/messages/ type: string created_timestamp: example: 2024-01-08 10:35:18 +0200 type: string description: > Chat creation time in the workspace timezone, formatted `YYYY-MM-DD HH:MM:SS ±ZZZZ`. last_message_uid: example: 4f43a9a0-b87e-4667-adfd-689674c3326c type: string last_message_timestamp: example: 2024-01-29 13:55:04 +0200 type: string unattended: example: false type: boolean description: > `true` when the AI Agent / autoresponder has flagged the chat as an **unattended customer** — an inbound message went unanswered and tripped the not-attended flow; cleared once the chat is handled. (Same underlying value as the webhook field `unattended_customer`.) photo: example: https://acme.com/logo.png type: string group_members: type: array items: type: object properties: name: example: John Doe type: string phone: type: string example: '+972502222222' role: type: string example: admin chat_id: type: integer example: 123456 description: > TimelinesAI chat ID of this member's one-on-one chat, if such a chat exists; otherwise `null`. is_allowed_to_message: example: true type: boolean description: > Whether messages can currently be sent into this chat via the API. `false` means sends to this chat will be rejected — common reasons are: the chat is a WhatsApp **broadcast list** (`@broadcast` JID) or a **channel/newsletter** (`@newsletter` JID), or the **WhatsApp account that owns the chat is currently disconnected**. `true` for normal one-on-one and group chats whose WhatsApp account is connected. ErrorResponse: required: - message - status type: object properties: message: type: string status: type: string example: error enum: - ok - error error_code: type: string description: >- Stable, machine-readable error code. Use this for branching in client integrations. example: validation_error enum: - missing_credentials - invalid_token - member_not_found - permission_denied - plan_feature_unavailable - quota_exceeded - rate_limit_exceeded - validation_error - not_supported - internal_error errors: type: array description: >- Per-field validation diagnostics. Present on `validation_error` responses; absent on auth/authorization/quota errors. items: $ref: '#/components/schemas/ValidationError' ValidationError: type: object required: - fields - msg properties: fields: type: array items: type: string description: >- Path of the offending field, as a list of keys/indexes from the request root. example: - url msg: type: string description: Validator message for that field. example: must be a valid http(s) URL responses: BadRequestError: description: Invalid parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' UnauthorizedError: description: Access token is missing or invalid AccessDenied: description: Access denied content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Specified entities not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: bearerAuth: type: http scheme: bearer ````