BAbase44

List agent conversation users

Changed on

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

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.

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.

<Note>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.</Note>

get/api/apps/{app_id}/agent-configs/conversation-users

Request

  • Base URL
    https://app.base44.com
  • URL
    https://app.base44.com/api/apps/{app_id}/agent-configs/conversation-users
  • Auth
    HTTP bearer

Path parameters

app_idstring required

ID of the app whose agents to read.

Query parameters

searchstring

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_filterstring

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_filterstring

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_filterstring

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_filterstring

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.

sortstring

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.

limitinteger

Items per page. Max 100. Defaults to 20, and 0 also means 20.

skipinteger

Number of users to skip before the page starts. Defaults to 0.

Response

A page of the users who have conversations with the app's agents.

totalinteger required

Total number of matching users.

Example response

{
  "items": [
    {
      "user_group_key": "68a1d2c3e4f5061728394a6c",
      "created_by_id": "68a1d2c3e4f5061728394a6c",
      "created_by_email": "jane@acme.com",
      "created_by_name": "Jane Cooper",
      "role": "user",
      "anonymous_visitor_id": "v_8f3k2m9q",
      "agent_names": [
        "support_agent"
      ],
      "agent_count": 1,
      "conversation_count": 2,
      "message_count": 6,
      "credit_count": 1.5,
      "latest_time": "2026-01-15T09:31:07",
      "agents": [
        {
          "agent_name": "support_agent",
          "last_message_preview": "Your order ships tomorrow and should arrive by Friday.",
          "last_message_time": "2026-01-15T09:31:07",
          "conversation_count": 2,
          "message_count": 6,
          "credit_count": 1.5,
          "conversations": [
            {
              "id": "68a1d2c3e4f5061728394a5b",
              "app_id": "6820f3a4e7b91d003c45a1f2",
              "agent_name": "support_agent",
              "title": "Order #1042 delivery date",
              "created_by_id": "68a1d2c3e4f5061728394a6c",
              "created_by_email": "jane@acme.com",
              "metadata": {
                "name": "Order #1042 delivery date"
              },
              "created_date": "2026-01-15T09:23:41",
              "updated_date": "2026-01-15T09:31:07",
              "message_count": 6,
              "credit_count": 1.5,
              "first_message_preview": "Order #1042 delivery date",
              "last_message_preview": "Your order ships tomorrow and should arrive by Friday.",
              "last_message_time": "2026-01-15T09:31:07",
              "answering": "ai",
              "channel": "whatsapp",
              "display_phone": "+15550100123",
              "display_name": "Dana Levi"
            }
          ],
          "answering": "ai"
        }
      ],
      "conversations": [
        {
          "id": "68a1d2c3e4f5061728394a5b",
          "app_id": "6820f3a4e7b91d003c45a1f2",
          "agent_name": "support_agent",
          "title": "Order #1042 delivery date",
          "created_by_id": "68a1d2c3e4f5061728394a6c",
          "created_by_email": "jane@acme.com",
          "metadata": {
            "name": "Order #1042 delivery date"
          },
          "created_date": "2026-01-15T09:23:41",
          "updated_date": "2026-01-15T09:31:07",
          "message_count": 6,
          "credit_count": 1.5,
          "first_message_preview": "Order #1042 delivery date",
          "last_message_preview": "Your order ships tomorrow and should arrive by Friday.",
          "last_message_time": "2026-01-15T09:31:07",
          "answering": "ai",
          "channel": "whatsapp",
          "display_phone": "+15550100123",
          "display_name": "Dana Levi"
        }
      ],
      "answering": "ai",
      "channels": [
        "whatsapp"
      ],
      "display_phone": "+15550100123",
      "display_name": "Dana Levi"
    }
  ],
  "total": 42
}

Changes

  • c23775445de2Revision changes
    • breaking

      query request parameter agent_filter list-of-types was narrowed by removing types null

    • breaking

      query request parameter limit list-of-types was narrowed by removing types null

    • breaking

      query request parameter owner_filter list-of-types was narrowed by removing types null

    • breaking

      query request parameter role_filter list-of-types was narrowed by removing types null

    • breaking

      query request parameter search list-of-types was narrowed by removing types null

    • breaking

      query request parameter skip list-of-types was narrowed by removing types null

    • breaking

      query request parameter sort list-of-types was narrowed by removing types null

    • breaking

      query request parameter time_filter list-of-types was narrowed by removing types null

    • breaking

      for the query request parameter limit, the type changed from no type to integer

    • breaking

      for the query request parameter skip, the type changed from no type to integer

    • info

      for the query request parameter agent_filter, the type was generalized from no type to string

    • info

      for the query request parameter owner_filter, the type was generalized from no type to string

    • info

      for the query request parameter role_filter, the type was generalized from no type to string

    • info

      for the query request parameter search, the type was generalized from no type to string

    • info

      for the query request parameter sort, the type was generalized from no type to string

    • info

      for the query request parameter time_filter, the type was generalized from no type to string

  • 60a68be6662eRevision changes
    • info

      added the optional property ////// to the response with the status

    • info

      added the optional property //// to the response with the status

    • info

      added the optional property // to the response with the status