--- title: "List agent conversation users" method: GET path: "/api/apps/{app_id}/agent-configs/conversation-users" --- # List agent conversation users `GET /api/apps/{app_id}/agent-configs/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. ## Path parameters - `app_id` string, required — ID of the app whose agents to read. ## Query parameters - `search` string, nullable — 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. - `owner_filter` string, nullable — 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`. - `agent_filter` string, nullable — 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. - `time_filter` string, nullable — Keep only conversations updated since midnight UTC (`today`), in the last 7 days (`7d`), or in the last 30 days (`30d`). Defaults to `all`. - `role_filter` string, nullable — 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`. - `sort` string, nullable — 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`. - `limit` integer, nullable — Items per page. Max 100. Defaults to 20, and `0` also means 20. - `skip` integer, nullable — Number of users to skip before the page starts. Defaults to 0. ## Response `200` A page of the users who have conversations with the app's agents. - ListConversationUsersResponse — A page of the app users who have conversations with the app's agents. - `items` ConversationUserSummary[], required — The users on this page. - `user_group_key` string, nullable — 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. - `created_by_id` string, nullable — ID of the app user who started the conversation. An anonymous visitor's conversation carries `anonymous`, `guest`, an empty string, or `null` instead. - `created_by_email` string, nullable — Email of the app user who started the conversation, or `null` for an anonymous visitor or an app user who no longer exists. - `created_by_name` string, nullable — Full name of the app user, or `null` if it isn't set. An anonymous visitor gets a generated display name instead. - `role` string, nullable — 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. - `is_anonymous_user` boolean — `true` for an anonymous visitor, and `false` for a signed-in app user. - `anonymous_visitor_id` string, nullable — ID that identifies an anonymous visitor across conversations. Read it only when `is_anonymous_user` is `true`. - `agent_names` string[] — Names of the agents the user has conversations with. - `agent_count` integer — Number of agents the user has conversations with. - `conversation_count` integer — Number of conversations the user has with the app's agents. - `message_count` integer — Number of messages across the user's conversations. - `credit_count` number — Credits charged for the agents' replies across the user's conversations. - `latest_time` string, date-time, nullable — When the user's newest conversation was last updated, as a UTC timestamp in ISO 8601 format. - `agents` ConversationAgentSummary[] — The user's conversations broken down by agent. - `agent_name` string, required — Name of the agent. - `last_message_preview` string, nullable — First 100 characters of the latest message in the user's newest conversation with this agent. - `last_message_time` string, date-time, nullable — When the user's newest conversation with this agent was last updated, as a UTC timestamp in ISO 8601 format. - `conversation_count` integer — Number of conversations the user has with this agent. - `message_count` integer — Number of messages across the user's conversations with this agent. - `credit_count` number — Credits charged for this agent's replies across the user's conversations with it. - `conversations` ConversationSummary[] — Up to 100 of the user's conversations with this agent. - `id` string, required — ID of the conversation. - `app_id` string, required — ID of the app. - `agent_name` string, required — Name of the agent the conversation is with. - `title` string, nullable — Title of the conversation, or `null` if it doesn't have one. - `created_by_id` string, nullable — ID of the app user who started the conversation. An anonymous visitor's conversation carries `anonymous`, `guest`, an empty string, or `null` instead. - `created_by_email` string, nullable — Email of the app user who started the conversation, or `null` for an anonymous visitor or an app user who no longer exists. - `metadata` object — 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. - `created_date` string, date-time, nullable — When the conversation was created, as a UTC timestamp in ISO 8601 format. - `updated_date` string, date-time, nullable — When the conversation was last updated, as a UTC timestamp in ISO 8601 format. - `message_count` integer — Number of messages in the conversation. - `credit_count` number — Credits charged for the agent's replies in the conversation. - `first_message_preview` string, nullable — First 100 characters of the conversation's title, or of its first visible message when it doesn't have a title. - `last_message_preview` string, nullable — First 100 characters of the conversation's latest message. - `last_message_time` string, date-time, nullable — When the conversation was last updated, as a UTC timestamp in ISO 8601 format. - `conversations` ConversationSummary[] — Up to 100 of the user's conversations across all of the app's agents. - `id` string, required — ID of the conversation. - `app_id` string, required — ID of the app. - `agent_name` string, required — Name of the agent the conversation is with. - `title` string, nullable — Title of the conversation, or `null` if it doesn't have one. - `created_by_id` string, nullable — ID of the app user who started the conversation. An anonymous visitor's conversation carries `anonymous`, `guest`, an empty string, or `null` instead. - `created_by_email` string, nullable — Email of the app user who started the conversation, or `null` for an anonymous visitor or an app user who no longer exists. - `metadata` object — 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. - `created_date` string, date-time, nullable — When the conversation was created, as a UTC timestamp in ISO 8601 format. - `updated_date` string, date-time, nullable — When the conversation was last updated, as a UTC timestamp in ISO 8601 format. - `message_count` integer — Number of messages in the conversation. - `credit_count` number — Credits charged for the agent's replies in the conversation. - `first_message_preview` string, nullable — First 100 characters of the conversation's title, or of its first visible message when it doesn't have a title. - `last_message_preview` string, nullable — First 100 characters of the conversation's latest message. - `last_message_time` string, date-time, nullable — When the conversation was last updated, as a UTC timestamp in ISO 8601 format. - `total` integer, required — Total number of matching users. ## Other responses - `400` — 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` — Missing or invalid credentials. - `403` — You don't have access to this app, or you used a workspace API key. - `404` — App not found. - `422` — `limit` or `skip` isn't a whole number. - `429` — Too many requests for this app in the last minute from personal API keys in your workspace. ## Changes > 22 revisions in range; 1 not diffed. - **2026-09-29** `d2b7ac8beb0c` — 1 info - endpoint added [Change history](https://skmtc.dev/adexad/apis/base44-app-management-api/changes/api/apps/:app_id/agent-configs/conversation-users/get.md) --- [API](https://skmtc.dev/adexad/apis/base44-app-management-api.md) · [All operations](https://skmtc.dev/adexad/apis/base44-app-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adexad/apis/base44-app-management-api/revisions/862b46d283f0?raw)