> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List agent conversation users
> This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.
Returns the app's users who have conversations with its agents, most recently active first. Each user comes with totals, a breakdown by agent, and up to 100 of their conversations.
The response carries personal data about the app's users. That includes their emails and names, and the start and end of their messages.
You can filter by:
- Text in the user's email or name
- Agent
- App role
- Recent activity
Results use offset pagination. Page with `limit` and `skip`, and stop once you've read `total` users. Open a conversation's messages with [Get agent conversation](/api-reference/get-agent-conversation).
This is limited to 60 requests a minute per app for each workspace's personal API keys, so every key in a workspace shares one allowance. Some workspaces have a different limit.
This endpoint accepts a personal API key, including a read-only one, from anyone with access to the app, viewers included. Workspace API keys are not authorized for it.
## OpenAPI
````yaml /developers/references/app-management/app-management-openapi.json get /api/apps/{app_id}/agent-configs/conversation-users
openapi: 3.1.0
info:
title: Base44 App Management API
version: 1.0.0
servers:
- url: https://app.base44.com
security:
- PersonalAccessTokenAuth: []
paths:
/api/apps/{app_id}/agent-configs/conversation-users:
get:
summary: List agent conversation users
description: >-
This API is in beta. Endpoints, fields, and behavior may still
change, so avoid depending on it in production.
Returns the app's users who have conversations with its agents, most
recently active first. Each user comes with totals, a breakdown by
agent, and up to 100 of their conversations.
The response carries personal data about the app's users. That includes
their emails and names, and the start and end of their messages.
You can filter by:
- Text in the user's email or name
- Agent
- App role
- Recent activity
Results use offset pagination. Page with `limit` and `skip`, and stop
once you've read `total` users. Open a conversation's messages with [Get
agent conversation](/api-reference/get-agent-conversation).
This is limited to 60 requests a minute per app for each workspace's
personal API keys, so every key in a workspace shares one allowance.
Some workspaces have a different limit.
This endpoint accepts a personal API key, including a read-only
one, from anyone with access to the app, viewers included. Workspace API
keys are not authorized for it.
operationId: >-
list_conversation_users_api_apps__app_id__agent_configs_conversation_users_get
parameters:
- name: app_id
in: path
required: true
schema:
type: string
description: ID of the app whose agents to read.
title: App Id
description: ID of the app whose agents to read.
example: 6820f3a4e7b91d003c45a1f2
- name: search
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Text to match, ignoring case, against the app user's email or full
name, the agent's name, or a WhatsApp phone number. Only the first
200 characters are used.
title: Search
description: >-
Text to match, ignoring case, against the app user's email or full
name, the agent's name, or a WhatsApp phone number. Only the first
200 characters are used.
example: jane
- name: owner_filter
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Whose conversations to include. Either `all`, `mine` for only the
ones you started as a user of the app, or `others` for everyone
else's. Defaults to `all`.
title: Owner Filter
description: >-
Whose conversations to include. Either `all`, `mine` for only the
ones you started as a user of the app, or `others` for everyone
else's. Defaults to `all`.
example: others
- name: agent_filter
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Names of the agents to include, as a comma-separated list or a
JSON array. For example, `support_agent,sales_agent`. Leave it out
for every agent.
title: Agent Filter
description: >-
Names of the agents to include, as a comma-separated list or a JSON
array. For example, `support_agent,sales_agent`. Leave it out for
every agent.
example: support_agent
- name: time_filter
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Keep only conversations updated since midnight UTC (`today`), in
the last 7 days (`7d`), or in the last 30 days (`30d`). Defaults
to `all`.
title: Time Filter
description: >-
Keep only conversations updated since midnight UTC (`today`), in the
last 7 days (`7d`), or in the last 30 days (`30d`). Defaults to
`all`.
example: 7d
- name: role_filter
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
App roles to include, as a comma-separated list or a JSON array of
`user`, `admin`, and `editor`. For example, `user,admin`.
Anonymous visitors are left out when you set it. Defaults to
`all`.
title: Role Filter
description: >-
App roles to include, as a comma-separated list or a JSON array of
`user`, `admin`, and `editor`. For example, `user,admin`. Anonymous
visitors are left out when you set it. Defaults to `all`.
example: user
- name: sort
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
Single field to sort users by, prefixed with `-` for descending.
Either `last_message_time`, `created_date`, `updated_date`,
`agent_count`, `conversation_count`, or `credit_count`. For
example, `-conversation_count` puts the most active users first.
Defaults to `-last_message_time`, and any other field sorts by
`last_message_time`.
title: Sort
description: >-
Single field to sort users by, prefixed with `-` for descending.
Either `last_message_time`, `created_date`, `updated_date`,
`agent_count`, `conversation_count`, or `credit_count`. For example,
`-conversation_count` puts the most active users first. Defaults to
`-last_message_time`, and any other field sorts by
`last_message_time`.
example: '-last_message_time'
- name: limit
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Items per page. Max 100. Defaults to 20, and `0` also means 20.
title: Limit
description: Items per page. Max 100. Defaults to 20, and `0` also means 20.
example: 20
- name: skip
in: query
required: false
schema:
anyOf:
- type: integer
- type: 'null'
description: Number of users to skip before the page starts. Defaults to 0.
title: Skip
description: Number of users to skip before the page starts. Defaults to 0.
example: 20
responses:
'200':
description: A page of the users who have conversations with the app's agents.
content:
application/json:
schema:
$ref: '#/components/schemas/ListConversationUsersResponse'
'400':
description: >-
A filter has a value it doesn't accept, `agent_filter` names an
agent the app doesn't have, `limit` or `skip` is negative or `skip`
is too large, `sort` lists more than one field, or `search` or
`role_filter` matches more than 5,000 app users.
'401':
description: Missing or invalid credentials.
'403':
description: You don't have access to this app, or you used a workspace API key.
'404':
description: App not found.
'422':
description: '`limit` or `skip` isn''t a whole number.'
'429':
description: >-
Too many requests for this app in the last minute from personal API
keys in your workspace.
components:
schemas:
ListConversationUsersResponse:
properties:
items:
items:
$ref: '#/components/schemas/ConversationUserSummary'
type: array
title: Items
description: The users on this page.
total:
type: integer
title: Total
description: Total number of matching users.
example: 42
type: object
required:
- items
- total
title: ListConversationUsersResponse
description: A page of the app users who have conversations with the app's agents.
ConversationUserSummary:
properties:
user_group_key:
anyOf:
- type: string
- type: 'null'
title: User Group Key
description: >-
Key the user's conversations are grouped under. It's the app user's
ID, `anonymous:` followed by the visitor ID for an anonymous
visitor, or `__anonymous_visitors__` for anonymous conversations
without a visitor ID.
example: 68a1d2c3e4f5061728394a6c
created_by_id:
anyOf:
- type: string
- type: 'null'
title: Created By Id
description: >-
ID of the app user who started the conversation. An anonymous
visitor's conversation carries `anonymous`, `guest`, an empty
string, or `null` instead.
example: 68a1d2c3e4f5061728394a6c
created_by_email:
anyOf:
- type: string
- type: 'null'
title: Created By Email
description: >-
Email of the app user who started the conversation, or `null` for an
anonymous visitor or an app user who no longer exists.
example: jane@acme.com
created_by_name:
anyOf:
- type: string
- type: 'null'
title: Created By Name
description: >-
Full name of the app user, or `null` if it isn't set. An anonymous
visitor gets a generated display name instead.
example: Jane Cooper
role:
anyOf:
- type: string
- type: 'null'
title: Role
description: >-
The app user's role in the app, such as `user` or `admin`. It's
`guest` for an anonymous visitor, or `null` if the app user no
longer exists.
example: user
is_anonymous_user:
type: boolean
title: Is Anonymous User
description: >-
`true` for an anonymous visitor, and `false` for a signed-in app
user.
default: false
example: false
anonymous_visitor_id:
anyOf:
- type: string
- type: 'null'
title: Anonymous Visitor Id
description: >-
ID that identifies an anonymous visitor across conversations. Read
it only when `is_anonymous_user` is `true`.
example: v_8f3k2m9q
agent_names:
items:
type: string
type: array
title: Agent Names
description: Names of the agents the user has conversations with.
example:
- support_agent
agent_count:
type: integer
title: Agent Count
description: Number of agents the user has conversations with.
default: 0
example: 1
conversation_count:
type: integer
title: Conversation Count
description: Number of conversations the user has with the app's agents.
default: 0
example: 2
message_count:
type: integer
title: Message Count
description: Number of messages across the user's conversations.
default: 0
example: 6
credit_count:
type: number
title: Credit Count
description: >-
Credits charged for the agents' replies across the user's
conversations.
default: 0
example: 1.5
latest_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Latest Time
description: >-
When the user's newest conversation was last updated, as a UTC
timestamp in ISO 8601 format.
example: '2026-01-15T09:31:07'
agents:
items:
$ref: '#/components/schemas/ConversationAgentSummary'
type: array
title: Agents
description: The user's conversations broken down by agent.
conversations:
items:
$ref: '#/components/schemas/ConversationSummary'
type: array
title: Conversations
description: >-
Up to 100 of the user's conversations across all of the app's
agents.
type: object
title: ConversationUserSummary
ConversationAgentSummary:
properties:
agent_name:
type: string
title: Agent Name
description: Name of the agent.
example: support_agent
last_message_preview:
anyOf:
- type: string
- type: 'null'
title: Last Message Preview
description: >-
First 100 characters of the latest message in the user's newest
conversation with this agent.
example: Your order ships tomorrow and should arrive by Friday.
last_message_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Message Time
description: >-
When the user's newest conversation with this agent was last
updated, as a UTC timestamp in ISO 8601 format.
example: '2026-01-15T09:31:07'
conversation_count:
type: integer
title: Conversation Count
description: Number of conversations the user has with this agent.
default: 0
example: 2
message_count:
type: integer
title: Message Count
description: Number of messages across the user's conversations with this agent.
default: 0
example: 6
credit_count:
type: number
title: Credit Count
description: >-
Credits charged for this agent's replies across the user's
conversations with it.
default: 0
example: 1.5
conversations:
items:
$ref: '#/components/schemas/ConversationSummary'
type: array
title: Conversations
description: Up to 100 of the user's conversations with this agent.
type: object
required:
- agent_name
title: ConversationAgentSummary
ConversationSummary:
properties:
id:
type: string
title: Id
description: ID of the conversation.
example: 68a1d2c3e4f5061728394a5b
app_id:
type: string
title: App Id
description: ID of the app.
example: 6820f3a4e7b91d003c45a1f2
agent_name:
type: string
title: Agent Name
description: Name of the agent the conversation is with.
example: support_agent
title:
anyOf:
- type: string
- type: 'null'
title: Title
description: Title of the conversation, or `null` if it doesn't have one.
example: 'Order #1042 delivery date'
created_by_id:
anyOf:
- type: string
- type: 'null'
title: Created By Id
description: >-
ID of the app user who started the conversation. An anonymous
visitor's conversation carries `anonymous`, `guest`, an empty
string, or `null` instead.
example: 68a1d2c3e4f5061728394a6c
created_by_email:
anyOf:
- type: string
- type: 'null'
title: Created By Email
description: >-
Email of the app user who started the conversation, or `null` for an
anonymous visitor or an app user who no longer exists.
example: jane@acme.com
metadata:
additionalProperties: true
type: object
title: Metadata
description: >-
Free-form data stored with the conversation. It holds whatever the
app set when it created the conversation, plus channel details such
as a WhatsApp user's phone number.
example:
name: 'Order #1042 delivery date'
created_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created Date
description: >-
When the conversation was created, as a UTC timestamp in ISO 8601
format.
example: '2026-01-15T09:23:41'
updated_date:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated Date
description: >-
When the conversation was last updated, as a UTC timestamp in ISO
8601 format.
example: '2026-01-15T09:31:07'
message_count:
type: integer
title: Message Count
description: Number of messages in the conversation.
default: 0
example: 6
credit_count:
type: number
title: Credit Count
description: Credits charged for the agent's replies in the conversation.
default: 0
example: 1.5
first_message_preview:
anyOf:
- type: string
- type: 'null'
title: First Message Preview
description: >-
First 100 characters of the conversation's title, or of its first
visible message when it doesn't have a title.
example: 'Order #1042 delivery date'
last_message_preview:
anyOf:
- type: string
- type: 'null'
title: Last Message Preview
description: First 100 characters of the conversation's latest message.
example: Your order ships tomorrow and should arrive by Friday.
last_message_time:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Message Time
description: >-
When the conversation was last updated, as a UTC timestamp in ISO
8601 format.
example: '2026-01-15T09:31:07'
type: object
required:
- id
- app_id
- agent_name
title: ConversationSummary
securitySchemes:
PersonalAccessTokenAuth:
type: http
scheme: bearer
description: 'Personal access token, sent as `Authorization: Bearer `.'
````