Get team member distribution of open conversations

Overview

Get the distribution of open conversations across your team members, including how many conversations each agent has and their average waiting time. This provides a snapshot of current workload distribution and helps identify bottlenecks. Perfect for real-time monitoring of team workload and ensuring balanced distribution of conversations.

Use Cases

Workload Dashboard: Monitor current workload across team
Load Balancing: Identify agents with too many/few conversations
Assignment Decisions: Determine which agent to assign new conversations to
Performance Monitoring: Track average waiting time per agent
Team Management: See who’s handling conversations and how quickly
Capacity Planning: Understand team capacity and bottlenecks

Authentication

This endpoint requires authentication using an API key. Include your API key in the request header:

x-api-key: your_api_key_here

Query Parameters

Parameter	Type	Required	Description
`agentIds`	string[]	No	Filter by specific team member IDs
`pipelineId`	string	No	Filter by specific pipeline
`stageIds`	string[]	No	Filter by specific stages
`hideArchived`	boolean	No	Hide archived conversations (default: true)
`hideUnassigned`	boolean	No	Hide unassigned conversations (default: true)

Response Structure

Field	Type	Description
`agentDistribution`	array	Array of agent distribution objects

Team Member Distribution Object

Field	Type	Description
`agent_id`	string (UUID)	Team member’s unique identifier
`agent_name`	string	Team member’s full name
`count`	number	Number of open conversations assigned to this team member
`averageWaitingTime`	number	Average waiting time in milliseconds

Example Request

curl --request GET \
  'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution' \
  --header 'x-api-key: your_api_key_here'

With Filters

curl --request GET \
  'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution?pipelineId=550e8400-e29b-41d4-a716-446655440000&hideArchived=true' \
  --header 'x-api-key: your_api_key_here'

Example Response

{
  "agentDistribution": [
    {
      "agent_id": "228d7a0d-9072-4ca8-939b-959b75cc606a",
      "agent_name": "Maria Rodriguez",
      "count": 15,
      "averageWaitingTime": 1800000
    },
    {
      "agent_id": "338e8b1e-8183-5db9-a4ab-a6ab86dd717b",
      "agent_name": "Carlos Silva",
      "count": 8,
      "averageWaitingTime": 900000
    },
    {
      "agent_id": "448f9c2f-9294-6eca-b5bc-b7bc97ee828c",
      "agent_name": "Ana Martinez",
      "count": 23,
      "averageWaitingTime": 3600000
    }
  ]
}

Common Use Cases

1. Find Team Member with Least Workload

const findMemberWithLeastWorkload = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const { agentDistribution } = await response.json();

  // Sort by count ascending
  const sortedByWorkload = agentDistribution.sort((a, b) => a.count - b.count);

  const leastBusy = sortedByWorkload[0];

  console.log(`Team member with least workload: ${leastBusy.agent_name}`);
  console.log(`Current conversations: ${leastBusy.count}`);

  return leastBusy;
};

2. Display Workload Dashboard

const displayWorkloadDashboard = async () => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const { agentDistribution } = await response.json();

  console.log('📊 Team Workload Distribution\n');

  agentDistribution.forEach((member) => {
    const avgMinutes = Math.floor(member.averageWaitingTime / 1000 / 60);
    const workloadLevel =
      member.count > 20
        ? '🔴 High'
        : member.count > 10
          ? '🟡 Medium'
          : '🟢 Low';

    console.log(`${member.agent_name}:`);
    console.log(`  Conversations: ${member.count} ${workloadLevel}`);
    console.log(`  Avg Wait Time: ${avgMinutes} minutes\n`);
  });

  return agentDistribution;
};

3. Balance Workload Alert

const checkWorkloadBalance = async (maxDifference = 10) => {
  const response = await fetch(
    'https://api.vambe.me/api/analytics/team/snapshot/agent-distribution',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const { agentDistribution } = await response.json();

  const counts = agentDistribution.map((a) => a.count);
  const max = Math.max(...counts);
  const min = Math.min(...counts);
  const difference = max - min;

  if (difference > maxDifference) {
    console.warn(`⚠️ Workload imbalance detected!`);
    console.warn(`Difference: ${difference} conversations`);
    console.warn(`Max: ${max} | Min: ${min}`);
    return { balanced: false, difference };
  }

  console.log('✅ Workload is balanced');
  return { balanced: true, difference };
};

4. Filter by Pipeline

const getSalesTeamWorkload = async (salesPipelineId) => {
  const response = await fetch(
    `https://api.vambe.me/api/analytics/team/snapshot/agent-distribution?pipelineId=${salesPipelineId}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

  const { agentDistribution } = await response.json();

  console.log(
    `Sales team handling ${agentDistribution.reduce((sum, a) => sum + a.count, 0)} conversations`,
  );

  return agentDistribution;
};

Average Waiting Time

The averageWaitingTime field is in milliseconds. To convert:

const millisToMinutes = (millis) => Math.floor(millis / 1000 / 60);
const millisToHours = (millis) => Math.floor(millis / 1000 / 60 / 60);

// Usage
agent.averageWaitingTime = 1800000;
console.log(`${millisToMinutes(agent.averageWaitingTime)} minutes`); // 30 minutes

Filters Explanation

agentIds: Comma-separated list to filter specific team members
pipelineId: Show only conversations in a specific pipeline
stageIds: Show only conversations in specific stages
hideArchived: Exclude archived conversations (default: true)
hideUnassigned: Exclude unassigned conversations (default: true)

Error Responses

Status Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
500	Internal Server Error - Something went wrong

GET /api/analytics/team/snapshot/average-first-response-time - Team average first response
GET /api/public/team-members/all - Get list of all team members

Notes

Real-time Snapshot: Returns current state of open conversations
Only Active Team Members: Team members with no conversations won’t appear
Waiting Time: Time since last customer message
Milliseconds: All time values in milliseconds

Headers

x-api-key

string

required

API key

Query Parameters

agentIds

string[]

Optional array of agent IDs to filter by specific agents

Example:

["agent-id-1", "agent-id-2"]

pipelineId

string

Optional pipeline ID to filter by specific pipeline

Example:

"pipeline-id-1"

stageIds

string[]

Optional array of stage IDs to filter by specific stages

Example:

["stage-id-1", "stage-id-2"]

hideArchived

boolean

Optional boolean to filter by archived conversations

Example:

true

hideUnassigned

boolean

required

Response

200 - application/json

Successfully retrieved agent distribution

agentDistribution

object[]

Show child attributes

Team Analytics

Contact Analytics

Performance Metrics

Event Tracking

Get team member distribution of open conversations

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Team Member Distribution Object

Example Request

With Filters

Example Response

Common Use Cases

1. Find Team Member with Least Workload

2. Display Workload Dashboard

3. Balance Workload Alert

4. Filter by Pipeline

Average Waiting Time

Filters Explanation

Error Responses

Notes

Headers

Query Parameters

Response

Team Analytics

Contact Analytics

Performance Metrics

Event Tracking

Documentation Index

​Overview

​Use Cases

​Authentication

​Query Parameters

​Response Structure

​Team Member Distribution Object

​Example Request

​With Filters

​Example Response

​Common Use Cases

​1. Find Team Member with Least Workload

​2. Display Workload Dashboard

​3. Balance Workload Alert

​4. Filter by Pipeline

​Average Waiting Time

​Filters Explanation

​Error Responses

​Related Endpoints

​Notes

Headers

Query Parameters

Response

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Team Member Distribution Object

Example Request

With Filters

Example Response

Common Use Cases

1. Find Team Member with Least Workload

2. Display Workload Dashboard

3. Balance Workload Alert

4. Filter by Pipeline

Average Waiting Time

Filters Explanation

Error Responses

Related Endpoints

Notes