Get average first response time

Overview

Get the average time it takes for your team to send the first response to new customer messages within a specific date range. This critical metric helps you measure customer service quality and SLA compliance. First response time is one of the most important customer service metrics, directly impacting customer satisfaction and retention.

Use Cases

SLA Monitoring: Track compliance with response time SLAs
Customer Satisfaction: Monitor key customer experience metric
Team Performance: Measure overall team responsiveness
Trend Analysis: Compare first response times across different periods
Improvement Tracking: Monitor the impact of process changes
Reporting: Generate executive reports on customer service quality

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
`startDate`	string	No	Start date (ISO 8601 format). Default: 7 days ago
`endDate`	string	No	End date (ISO 8601 format). Default: today
`agentIds`	string[]	No	Filter by specific team member IDs
`pipelineId`	string	No	Filter by specific pipeline

Default Range: If no dates provided, returns data for the last 7 days.

Response Structure

Field	Type	Description
`averageFirstResponseTime`	number	Average first response time in seconds

Example Requests

Get Last 7 Days (Default)

curl --request GET \
  'https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time' \
  --header 'x-api-key: your_api_key_here'

Get Specific Date Range

curl --request GET \
  'https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time?startDate=2024-09-01&endDate=2024-09-30' \
  --header 'x-api-key: your_api_key_here'

Filter by Pipeline and Team Members

curl --request GET \
  'https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time?pipelineId=550e8400-e29b-41d4-a716-446655440000&agentIds=member-1,member-2' \
  --header 'x-api-key: your_api_key_here'

Example Response

{
  "averageFirstResponseTime": 300
}

This means the average first response time is 300 seconds (5 minutes).

Common Use Cases

1. Display Response Time Metric

const displayFirstResponseTime = async () => {
  const response = await fetch(
    'https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  const minutes = Math.floor(averageFirstResponseTime / 60);
  const seconds = averageFirstResponseTime % 60;

  console.log(`⏱️ Average First Response Time: ${minutes}m ${seconds}s`);

  // Display as badge
  const status =
    averageFirstResponseTime < 300
      ? '🟢 Excellent'
      : averageFirstResponseTime < 600
        ? '🟡 Good'
        : '🔴 Needs Improvement';

  console.log(`Status: ${status}`);

  return { averageFirstResponseTime, minutes, seconds, status };
};

2. Compare Different Time Periods

const compareMonthlyPerformance = async () => {
  // Last month
  const lastMonthStart = new Date();
  lastMonthStart.setMonth(lastMonthStart.getMonth() - 1);
  lastMonthStart.setDate(1);

  const lastMonthEnd = new Date();
  lastMonthEnd.setDate(0);

  const lastMonthResponse = await fetch(
    `https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time?startDate=${lastMonthStart.toISOString().split('T')[0]}&endDate=${lastMonthEnd.toISOString().split('T')[0]}`,
    {
      headers: { 'x-api-key': 'your_api_key_here' },
    },
  );

  const lastMonth = await lastMonthResponse.json();

  // This month
  const thisMonthStart = new Date();
  thisMonthStart.setDate(1);

  const thisMonthResponse = await fetch(
    `https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time?startDate=${thisMonthStart.toISOString().split('T')[0]}`,
    {
      headers: { 'x-api-key': 'your_api_key_here' },
    },
  );

  const thisMonth = await thisMonthResponse.json();

  const improvement =
    lastMonth.averageFirstResponseTime - thisMonth.averageFirstResponseTime;

  console.log('📈 Monthly Comparison:');
  console.log(
    `Last Month: ${Math.floor(lastMonth.averageFirstResponseTime / 60)}m`,
  );
  console.log(
    `This Month: ${Math.floor(thisMonth.averageFirstResponseTime / 60)}m`,
  );
  console.log(
    `${improvement > 0 ? '✅ Improved' : '⚠️ Slower'} by ${Math.floor(Math.abs(improvement) / 60)}m`,
  );

  return { lastMonth, thisMonth, improvement };
};

3. SLA Compliance Check

const checkSLACompliance = async (slaMinutes = 5) => {
  const response = await fetch(
    'https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time',
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  const actualMinutes = averageFirstResponseTime / 60;
  const compliant = actualMinutes <= slaMinutes;

  console.log(`SLA Target: ${slaMinutes} minutes`);
  console.log(`Actual: ${actualMinutes.toFixed(2)} minutes`);
  console.log(`Status: ${compliant ? '✅ Compliant' : '❌ Non-Compliant'}`);

  return {
    slaMinutes,
    actualMinutes,
    compliant,
    difference: actualMinutes - slaMinutes,
  };
};

4. Compare Team Member Performance

const compareTeamMemberPerformance = async (memberIds) => {
  const results = [];

  for (const memberId of memberIds) {
    const response = await fetch(
      `https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time?agentIds=${memberId}`,
      {
        headers: {
          'x-api-key': 'your_api_key_here',
        },
      },
    );

    const data = await response.json();
    results.push({
      memberId,
      firstResponseTime: data.averageFirstResponseTime,
    });
  }

  // Sort by fastest
  results.sort((a, b) => a.firstResponseTime - b.firstResponseTime);

  console.log('Team Member First Response Time Comparison:');
  results.forEach((r, idx) => {
    console.log(
      `${idx + 1}. Member ${r.memberId}: ${Math.floor(r.firstResponseTime / 60)}m`,
    );
  });

  return results;
};

5. Weekly Performance Report

const getWeeklyReport = async () => {
  const today = new Date();
  const weekAgo = new Date(today.getTime() - 7 * 24 * 60 * 60 * 1000);

  const response = await fetch(
    `https://api.vambe.ai/api/analytics/team/snapshot/average-first-response-time?startDate=${weekAgo.toISOString().split('T')[0]}&endDate=${today.toISOString().split('T')[0]}`,
    {
      headers: {
        'x-api-key': 'your_api_key_here',
      },
    },
  );

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

  const report = {
    period: 'Last 7 Days',
    startDate: weekAgo.toISOString().split('T')[0],
    endDate: today.toISOString().split('T')[0],
    averageFirstResponseSeconds: averageFirstResponseTime,
    averageFirstResponseMinutes: (averageFirstResponseTime / 60).toFixed(2),
    rating:
      averageFirstResponseTime < 180
        ? 'Excellent (< 3min)'
        : averageFirstResponseTime < 300
          ? 'Good (< 5min)'
          : averageFirstResponseTime < 600
            ? 'Fair (< 10min)'
            : 'Needs Improvement (> 10min)',
  };

  console.log('📊 Weekly Performance Report:', report);

  return report;
};

Date Format

Dates should be in ISO 8601 format (YYYY-MM-DD):

✅ Correct: "2024-09-30"
✅ Correct: "2024-01-15"
❌ Incorrect: "09/30/2024"
❌ Incorrect: "30-09-2024"

Time Zone Considerations

Dates are interpreted in your account’s configured time zone
Response time calculations respect your business hours
Default date range: Last 7 days from current time

Error Responses

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

Performance Benchmarks

Typical first response time benchmarks:

Time Range	Rating	Use Case
< 3 minutes	Excellent ⭐⭐⭐	Premium support, urgent
3-5 minutes	Good ⭐⭐	Standard support
5-10 minutes	Fair ⭐	Non-urgent inquiries
> 10 minutes	Needs Work ⚠️	Consider staffing/processes

GET /api/public/analytics/agents/response-time - Individual team member metrics
GET /api/analytics/team/snapshot/agent-distribution - Current workload distribution
Analytics Overview - Complete analytics guide

Notes

First Response Only: Measures time to FIRST team member response per conversation
Team Average: Aggregates across all team members (or filtered subset)
Seconds Unit: Response time returned in seconds
Default Period: Last 7 days if no dates specified
Business Impact: Lower times generally correlate with higher satisfaction

Headers

x-api-key

string

required

API key

Query Parameters

startDate

string

Start date (ISO 8601). Defaults to today-7d 00:00.

Example:

"2025-05-27"

endDate

string

End date (ISO 8601). Defaults to today 23:59.

Example:

"2025-06-03"

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"

Response

200 - application/json

Successfully retrieved average first response time

averageFirstResponseTime

number

Average first response time in seconds

Example:

300

Team Analytics

Contact Analytics

Performance Metrics

Event Tracking

Get average first response time

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Example Requests

Get Last 7 Days (Default)

Get Specific Date Range

Filter by Pipeline and Team Members

Example Response

Common Use Cases

1. Display Response Time Metric

2. Compare Different Time Periods

3. SLA Compliance Check

4. Compare Team Member Performance

5. Weekly Performance Report

Date Format

Time Zone Considerations

Error Responses

Performance Benchmarks

Notes

Headers

Query Parameters

Response

Team Analytics

Contact Analytics

Performance Metrics

Event Tracking

​Overview

​Use Cases

​Authentication

​Query Parameters

​Response Structure

​Example Requests

​Get Last 7 Days (Default)

​Get Specific Date Range

​Filter by Pipeline and Team Members

​Example Response

​Common Use Cases

​1. Display Response Time Metric

​2. Compare Different Time Periods

​3. SLA Compliance Check

​4. Compare Team Member Performance

​5. Weekly Performance Report

​Date Format

​Time Zone Considerations

​Error Responses

​Performance Benchmarks

​Related Endpoints

​Notes

Headers

Query Parameters

Response

Overview

Use Cases

Authentication

Query Parameters

Response Structure

Example Requests

Get Last 7 Days (Default)

Get Specific Date Range

Filter by Pipeline and Team Members

Example Response

Common Use Cases

1. Display Response Time Metric

2. Compare Different Time Periods

3. SLA Compliance Check

4. Compare Team Member Performance

5. Weekly Performance Report

Date Format

Time Zone Considerations

Error Responses

Performance Benchmarks

Related Endpoints

Notes