> ## Documentation Index
> Fetch the complete documentation index at: https://www.text.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List chats
> Returns summaries of the chats an agent has access to.
**Required scopes:** `chats--all:ro` or `chats--access:ro`
## OpenAPI
````yaml /api/agent-chat/v3.6/openapi.json post /action/list_chats
openapi: 3.0.0
info:
title: Agent Chat API
description: >-
The Agent Chat API allows you to manage chats, threads, events, and agent
state.
version: '3.6'
servers:
- url: https://api.livechatinc.com/v3.6/agent
description: Production server
security: []
paths:
/action/list_chats:
post:
tags:
- Chats
summary: List chats
description: Returns summaries of the chats an agent has access to.
operationId: list-chats
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ListChatsRequest'
example: {}
responses:
'200':
description: Chat summaries.
content:
application/json:
schema:
$ref: '#/components/schemas/ListChatsResponse'
example:
next_page_id: MTUxNzM5ODEzMTQ5Ng==
chats_summary:
- id: PJ0MRSHTDG
last_event_per_type:
message:
thread_id: K600PKZON8
thread_created_at: '2026-06-07T07:11:28.288340Z'
event:
id: Q298LUVPRH_1
created_at: '2026-06-09T12:01:18.909000Z'
visibility: all
type: message
text: hello world
author_id: b7eff798-f8df-4364-8059-649c35c9ed0c
users:
- id: b7eff798-f8df-4364-8059-649c35c9ed0c
type: customer
present: true
created_at: '2026-06-17T08:53:20.693553+01:00'
- id: smith@example.com
name: Agent Smith
email: smith@example.com
type: agent
present: true
avatar: https://example.com/avatar.jpg
visibility: all
last_thread_summary:
id: K600PKZON8
created_at: '2026-06-07T07:11:28.288340Z'
user_ids:
- b7eff798-f8df-4364-8059-649c35c9ed0c
- smith@example.com
properties: {}
active: true
access:
group_ids:
- 0
properties: {}
access:
group_ids:
- 0
is_followed: true
found_chats: 4
security:
- PersonalAccessToken: []
- OAuth2BearerToken:
- chats--all:ro
components:
schemas:
ListChatsRequest:
type: object
properties:
filters:
type: object
description: >-
When paginating, filters provided in the first request are
remembered for subsequent pages. Providing a new `filters` object
will result in a `validation` error. To reset filters, start
paginating with a new set.
properties:
active:
type: boolean
description: >-
If `true`: returns active chats only. If `false`: returns
inactive chats only. If not provided: returns both.
include_chats_without_threads:
type: boolean
default: true
description: 'If `true`: includes chats without any threads.'
group_ids:
type: array
items:
type: integer
maxItems: 200
description: Array of group IDs.
properties:
type: object
description: >-
Property filters in the format
`..`. Filter types: `exists`
(`bool`), `values` (`type[]`), `exclude_values` (`type[]`). Only
one value allowed per property.
additionalProperties: true
sort_order:
type: string
enum:
- asc
- desc
default: desc
description: '`asc` for oldest chats first, `desc` for newest chats first.'
limit:
type: integer
default: 10
maximum: 100
description: Maximum number of records per page.
page_id:
type: string
description: Pagination token.
ListChatsResponse:
type: object
properties:
chats_summary:
type: array
items:
$ref: '#/components/schemas/ChatSummary'
description: >-
Array of [chat summary
objects](/api/agent-chat/v3.6/data-structures#chat-summaries).
found_chats:
type: integer
description: Estimated number of found chats.
next_page_id:
type: string
description: Pagination token for the next page.
previous_page_id:
type: string
description: Pagination token for the previous page.
ChatSummary:
type: object
description: >-
Chat summary object. For full field details, see the [Agent Chat API
data structures reference](/api/agent-chat/v3.6/data-structures).
properties:
id:
type: string
description: Chat ID.
users:
type: array
items:
$ref: '#/components/schemas/User'
description: Chat users.
last_event_per_type:
type: object
description: Map of the last event per event type.
additionalProperties: true
last_thread_summary:
$ref: '#/components/schemas/Thread'
properties:
$ref: '#/components/schemas/Properties'
access:
$ref: '#/components/schemas/Access'
is_followed:
type: boolean
description: Whether the requester follows the chat.
order:
type: integer
description: Order of the chat in the list.
User:
type: object
description: >-
User object (agent or customer). For full field details, see the [Agent
Chat API data structures
reference](/api/agent-chat/v3.6/data-structures).
properties:
id:
type: string
description: User ID.
type:
type: string
enum:
- agent
- customer
description: User type.
name:
type: string
description: User's display name.
email:
type: string
description: User's email address (agents only).
present:
type: boolean
description: Whether the user is currently present in the chat.
Thread:
type: object
description: >-
Thread object. For full field details, see the [Agent Chat API data
structures reference](/api/agent-chat/v3.6/data-structures).
properties:
id:
type: string
description: Thread ID.
chat_id:
type: string
description: Chat ID.
active:
type: boolean
description: Whether the thread is active.
user_ids:
type: array
items:
type: string
description: IDs of users present in the thread.
events:
type: array
items:
$ref: '#/components/schemas/Event'
description: Thread events.
properties:
$ref: '#/components/schemas/Properties'
access:
$ref: '#/components/schemas/Access'
created_at:
type: string
format: date-time
description: Thread creation timestamp (RFC3339 with microseconds).
previous_thread_id:
type: string
description: ID of the previous thread in the chat (if exists).
next_thread_id:
type: string
description: ID of the next thread in the chat (if exists).
Properties:
type: object
description: Custom properties organized by namespace, then property name.
additionalProperties:
type: object
additionalProperties: true
Access:
type: object
description: >-
[Access object](/api/agent-chat/v3.6/data-structures#access) defining
which groups can access the chat or thread.
properties:
group_ids:
type: array
items:
type: integer
description: Array of group IDs with access. `0` means all groups.
Event:
type: object
description: >-
Event object. Event types include `message`, `file`, `form`,
`filled_form`, `rich_message`, `custom`, `system_message`, and `system`.
For full field details per type, see the [Agent Chat API data structures
reference](/api/agent-chat/v3.6/data-structures).
properties:
id:
type: string
description: Event ID.
type:
type: string
description: Event type.
created_at:
type: string
format: date-time
description: Event creation timestamp (RFC3339 with microseconds).
author_id:
type: string
description: ID of the event author.
visibility:
type: string
enum:
- all
- agents
description: Event visibility.
properties:
$ref: '#/components/schemas/Properties'
securitySchemes:
PersonalAccessToken:
description: >-
Use your `account ID` as the username and your personal access token
(PAT) as the password, or pass a Base64-encoded value directly in the
Authorization header. For more information, see the personal access tokens
guide.
type: http
scheme: basic
OAuth2BearerToken:
description: >-
This API uses OAuth2 with the implicit grant flow. Learn about
the implicit grant flow.
type: oauth2
flows:
implicit:
authorizationUrl: https://accounts.livechat.com
scopes:
chats--all:ro: Read all chats
chats--all:rw: Read and write all chats
chats--access:ro: Read chats from groups the agent is a member of
chats--access:rw: Read and write chats from groups the agent is a member of
authorizationCode:
authorizationUrl: https://accounts.livechat.com
tokenUrl: https://accounts.livechat.com/token
scopes:
chats--all:ro: Read all chats
chats--all:rw: Read and write all chats
chats--access:ro: Read chats from groups the agent is a member of
chats--access:rw: Read and write chats from groups the agent is a member of
````