Sign in

List agent conversation users

<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

Path parameters

app_idstring required

ID of the app whose agents to read.

ID of the app whose agents to read.

Query parameters

searchstring 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.

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

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

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

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

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

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 nullable

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

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

skipinteger nullable

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

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"
            }
          ]
        }
      ],
      "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"
        }
      ]
    }
  ],
  "total": 42
}

Changes

Changed in 1 of the 22 revisions of this API.1

Of the 22 revisions, 1 has no diff computed.