Customer Support API

The Customer Support API provides read-only access to customer support queries handled by AI agents and their outcomes. This API allows you to track how many customer support queries your agents have processed, their resolution status, response times, and success rates to measure agent performance and customer satisfaction.

Authentication

All endpoints require API key authentication via the x-api-key header.

curl -H "x-api-key: YOUR_API_KEY" https://api.aloochat.ai/customer-support

Base URL

https://api.aloochat.ai/customer-support

Endpoints

List Agent-Handled Support Queries

Retrieve a paginated list of customer support queries that have been handled by your AI agents, including their outcomes and performance metrics.

Endpoint: GET /customer-support

Query Parameters:

skip (integer, optional): Number of queries to skip (default: 0)
limit (integer, optional): Maximum number of queries to return (default: 50, max: 100)
query_type (string, optional): Filter by query type (bug_report, feature_request, general_inquiry, technical_support, billing, account)
status (string, optional): Filter by status (open, in_progress, resolved, closed)
priority (string, optional): Filter by priority (low, medium, high, urgent)
agent_id (string, optional): Filter by assigned agent ID
user_id (string, optional): Filter by user ID who created the query
start_date (string, optional): Filter queries created after this date (ISO 8601 format)
end_date (string, optional): Filter queries created before this date (ISO 8601 format)

curl -X GET "https://api.aloochat.ai/customer-support?limit=10&status=open" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://api.aloochat.ai/customer-support?limit=10&status=open', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const queries = await response.json();
console.log(queries);

import requests
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
params = {
    'limit': 10,
    'status': 'open'
}
 
response = requests.get(
    'https://api.aloochat.ai/customer-support',
    headers=headers,
    params=params
)
 
queries = response.json()
print(queries)

Response:

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "company_id": "123e4567-e89b-12d3-a456-426614174001",
      "user_id": "123e4567-e89b-12d3-a456-426614174002",
      "agent_id": "123e4567-e89b-12d3-a456-426614174003",
      "deployment_id": "123e4567-e89b-12d3-a456-426614174004",
      "conversation_id": "123e4567-e89b-12d3-a456-426614174005",
      "query_type": "technical_support",
      "status": "open",
      "priority": "high",
      "subject": "Billing inquiry - subscription upgrade",
      "description": "Customer wants to upgrade from Basic to Pro plan and needs pricing information.",
      "resolution": "Agent successfully provided pricing details and guided customer through upgrade process. Customer upgraded to Pro plan.",
      "metadata": {
        "agent_actions_count": 3,
        "tools_used": ["billing_tool", "email_tool"],
        "customer_satisfaction": 5,
        "resolution_method": "automated",
        "escalated_to_human": false
      },
      "created_at": "2024-01-10T10:00:00Z",
      "updated_at": "2024-01-10T10:00:00Z",
      "resolved_at": "2024-01-10T14:30:00Z",
      "user": {
        "id": "123e4567-e89b-12d3-a456-426614174002",
        "email": "user@example.com",
        "name": "John Doe"
      },
      "agent": {
        "id": "123e4567-e89b-12d3-a456-426614174003",
        "title": "Billing Support Agent",
        "task_description": "Handle billing and subscription queries",
        "performance_metrics": {
          "total_queries_handled": 245,
          "avg_resolution_time": 18.5,
          "success_rate": 92.3,
          "customer_satisfaction_avg": 4.6
        }
      },
      "notes": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174006",
          "query_id": "123e4567-e89b-12d3-a456-426614174000",
          "user_id": "123e4567-e89b-12d3-a456-426614174007",
          "content": "Agent successfully resolved billing inquiry. Customer upgraded to Pro plan. Follow-up email sent with welcome package.",
          "is_internal": false,
          "created_at": "2024-01-10T11:00:00Z",
          "user": {
            "id": "123e4567-e89b-12d3-a456-426614174007",
            "email": "support@example.com",
            "name": "Support Team"
          }
        }
      ]
    }
  ],
  "total": 45,
  "skip": 0,
  "limit": 10
}

Get Support Query Details

Retrieve detailed information about a specific support query.

Endpoint: GET /customer-support/{query_id}

curl -X GET "https://api.aloochat.ai/customer-support/123e4567-e89b-12d3-a456-426614174000" \
  -H "x-api-key: YOUR_API_KEY"

const queryId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.aloochat.ai/customer-support/${queryId}`, {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const query = await response.json();
console.log(query);

import requests
 
query_id = '123e4567-e89b-12d3-a456-426614174000'
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    f'https://api.aloochat.ai/customer-support/{query_id}',
    headers=headers
)
 
query = response.json()
print(query)

Get Support Query Notes

Retrieve all notes associated with a specific support query.

Endpoint: GET /customer-support/{query_id}/notes

Query Parameters:

skip (integer, optional): Number of notes to skip (default: 0)
limit (integer, optional): Maximum number of notes to return (default: 50)
include_internal (boolean, optional): Include internal notes (default: true)

curl -X GET "https://api.aloochat.ai/customer-support/123e4567-e89b-12d3-a456-426614174000/notes" \
  -H "x-api-key: YOUR_API_KEY"

const queryId = '123e4567-e89b-12d3-a456-426614174000';
const response = await fetch(`https://api.aloochat.ai/customer-support/${queryId}/notes`, {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const notes = await response.json();
console.log(notes);

import requests
 
query_id = '123e4567-e89b-12d3-a456-426614174000'
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    f'https://api.aloochat.ai/customer-support/{query_id}/notes',
    headers=headers
)
 
notes = response.json()
print(notes)

Get Agent Performance Dashboard

Retrieve dashboard data showing how your AI agents are performing in handling customer support queries, including resolution rates, response times, and customer satisfaction metrics.

Endpoint: GET /customer-support/dashboard

Query Parameters:

start_date (string, optional): Start date for dashboard data (ISO 8601 format)
end_date (string, optional): End date for dashboard data (ISO 8601 format)
recent_limit (integer, optional): Number of recent queries to include (default: 10)

curl -X GET "https://api.aloochat.ai/customer-support/dashboard" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://api.aloochat.ai/customer-support/dashboard', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const dashboard = await response.json();
console.log(dashboard);

import requests
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    'https://api.aloochat.ai/customer-support/dashboard',
    headers=headers
)
 
dashboard = response.json()
print(dashboard)

Response:

{
  "total_queries": 150,
  "open_queries": 25,
  "in_progress_queries": 15,
  "resolved_queries": 95,
  "closed_queries": 15,
  "avg_resolution_time": 24.5,
  "agent_handled_queries": 142,
  "human_escalated_queries": 8,
  "agent_success_rate": 94.7,
  "avg_customer_satisfaction": 4.3,
  "queries_by_type": {
    "technical_support": 60,
    "bug_report": 30,
    "feature_request": 25,
    "general_inquiry": 20,
    "billing": 10,
    "account": 5
  },
  "queries_by_priority": {
    "low": 50,
    "medium": 70,
    "high": 25,
    "urgent": 5
  },
  "recent_queries": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "subject": "Billing inquiry - subscription upgrade",
      "status": "resolved",
      "priority": "medium",
      "created_at": "2024-01-10T10:00:00Z",
      "resolved_at": "2024-01-10T14:30:00Z",
      "agent_id": "123e4567-e89b-12d3-a456-426614174003",
      "resolution_method": "automated",
      "customer_satisfaction": 5
    }
  ],
  "top_performing_agents": [
    {
      "agent_id": "123e4567-e89b-12d3-a456-426614174003",
      "agent_name": "Billing Support Agent",
      "queries_handled": 45,
      "success_rate": 96.2,
      "avg_resolution_time": 16.8,
      "customer_satisfaction": 4.7
    }
  ]
}

Get Support Statistics

Retrieve detailed statistics about customer support queries.

Endpoint: GET /customer-support/stats

Query Parameters:

start_date (string, optional): Start date for statistics (ISO 8601 format)
end_date (string, optional): End date for statistics (ISO 8601 format)
group_by (string, optional): Group statistics by (day, week, month)

curl -X GET "https://api.aloochat.ai/customer-support/stats" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://api.aloochat.ai/customer-support/stats', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const stats = await response.json();
console.log(stats);

import requests
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
response = requests.get(
    'https://api.aloochat.ai/customer-support/stats',
    headers=headers
)
 
stats = response.json()
print(stats)

Response:

{
  "total_queries": 150,
  "by_status": {
    "open": 25,
    "in_progress": 15,
    "resolved": 95,
    "closed": 15
  },
  "by_type": {
    "technical_support": 60,
    "bug_report": 30,
    "feature_request": 25,
    "general_inquiry": 20,
    "billing": 10,
    "account": 5
  },
  "by_priority": {
    "low": 50,
    "medium": 70,
    "high": 25,
    "urgent": 5
  },
  "resolution_metrics": {
    "avg_resolution_time": 24.5,
    "median_resolution_time": 18.0,
    "total_resolved": 95,
    "agent_resolved": 89,
    "human_resolved": 6,
    "automated_resolution_rate": 93.7
  },
  "agent_performance": {
    "total_agents_active": 12,
    "avg_queries_per_agent": 11.8,
    "top_agent_success_rate": 98.1,
    "agents_above_target": 10
  }
}

Get Support Analytics

Retrieve analytics data including trends and time series information.

Endpoint: GET /customer-support/analytics

Query Parameters:

start_date (string, optional): Start date for analytics (ISO 8601 format)
end_date (string, optional): End date for analytics (ISO 8601 format)
granularity (string, optional): Data granularity (day, week, month, default: day)

curl -X GET "https://api.aloochat.ai/customer-support/analytics?granularity=week" \
  -H "x-api-key: YOUR_API_KEY"

const response = await fetch('https://api.aloochat.ai/customer-support/analytics?granularity=week', {
  method: 'GET',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
 
const analytics = await response.json();
console.log(analytics);

import requests
 
headers = {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
}
 
params = {'granularity': 'week'}
 
response = requests.get(
    'https://api.aloochat.ai/customer-support/analytics',
    headers=headers,
    params=params
)
 
analytics = response.json()
print(analytics)

Response:

{
  "time_series": [
    {
      "date": "2024-01-01",
      "queries_created": 12,
      "queries_resolved": 8
    },
    {
      "date": "2024-01-08",
      "queries_created": 15,
      "queries_resolved": 12
    }
  ],
  "trends": {
    "query_volume_trend": "increasing",
    "resolution_time_trend": "improving"
  },
  "top_categories": [
    {
      "category": "technical_support",
      "count": 60,
      "percentage": 40.0
    },
    {
      "category": "bug_report",
      "count": 30,
      "percentage": 20.0
    }
  ]
}

Query Types

bug_report: Bug reports and issues
feature_request: Feature requests and enhancements
general_inquiry: General questions and inquiries
technical_support: Technical support requests
billing: Billing and payment related queries
account: Account management queries

Status Values

open: Query is newly created and awaiting assignment
in_progress: Query is being actively worked on
resolved: Query has been resolved but not yet closed
closed: Query is completed and closed

Priority Levels

low: General inquiries, non-urgent issues
medium: Standard support requests
high: Important issues affecting functionality
urgent: Critical issues requiring immediate attention

Error Handling

The API returns standard HTTP status codes:

200 OK: Request successful
400 Bad Request: Invalid request parameters
401 Unauthorized: Invalid or missing API key
403 Forbidden: Access denied
404 Not Found: Resource not found
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Error responses include details:

{
  "error": "ValidationError",
  "message": "Invalid query_type parameter",
  "statusCode": 400,
  "timestamp": "2024-01-10T10:00:00Z",
  "path": "/customer-support"
}

Rate Limiting

API requests are rate-limited to prevent abuse. Current limits:

1000 requests per hour per API key
Burst limit of 100 requests per minute

Best Practices

Pagination: Use skip and limit parameters for large datasets
Filtering: Apply appropriate filters to get relevant data
Caching: Cache dashboard and analytics data to reduce API calls
Error Handling: Implement proper error handling for all API calls
Date Ranges: Use date filters for better performance with large datasets

Use Cases

Agent Performance Dashboard

// Create a comprehensive agent performance dashboard
async function createAgentPerformanceDashboard() {
  const [dashboard, stats] = await Promise.all([
    fetch('https://api.aloochat.ai/customer-support/dashboard', {
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    }).then(r => r.json()),
    fetch('https://api.aloochat.ai/customer-support/stats', {
      headers: { 'x-api-key': 'YOUR_API_KEY' }
    }).then(r => r.json())
  ]);
 
  return {
    overview: dashboard,
    statistics: stats,
    agentMetrics: {
      totalHandled: dashboard.agent_handled_queries,
      successRate: dashboard.agent_success_rate,
      avgSatisfaction: dashboard.avg_customer_satisfaction,
      topPerformers: dashboard.top_performing_agents
    }
  };
}
 
// Track agent performance for specific agent
async function getAgentPerformance(agentId) {
  const response = await fetch(`https://api.aloochat.ai/customer-support?agent_id=${agentId}&limit=100`, {
    headers: { 'x-api-key': 'YOUR_API_KEY' }
  });
  
  const queries = await response.json();
  
  // Calculate performance metrics
  const resolved = queries.data.filter(q => q.status === 'resolved').length;
  const avgSatisfaction = queries.data
    .filter(q => q.metadata.customer_satisfaction)
    .reduce((sum, q) => sum + q.metadata.customer_satisfaction, 0) / queries.data.length;
  
  return {
    totalQueries: queries.total,
    resolvedQueries: resolved,
    successRate: (resolved / queries.total * 100).toFixed(1),
    avgCustomerSatisfaction: avgSatisfaction.toFixed(1)
  };
}

Agent Performance Monitoring

import requests
from datetime import datetime, timedelta
 
def monitor_agent_performance():
    """Monitor agent performance and identify issues"""
    headers = {'x-api-key': 'YOUR_API_KEY'}
    
    # Get dashboard data
    dashboard_response = requests.get(
        'https://api.aloochat.ai/customer-support/dashboard',
        headers=headers
    )
    
    dashboard = dashboard_response.json()
    
    # Check agent performance metrics
    if dashboard['agent_success_rate'] < 90:
        print(f"⚠️  Agent success rate is {dashboard['agent_success_rate']:.1f}% (below 90% target)")
    
    if dashboard['avg_customer_satisfaction'] < 4.0:
        print(f"⚠️  Customer satisfaction is {dashboard['avg_customer_satisfaction']:.1f}/5 (below 4.0 target)")
    
    # Get queries that needed human escalation
    escalated_response = requests.get(
        'https://api.aloochat.ai/customer-support',
        headers=headers,
        params={'limit': 50}
    )
    
    queries = escalated_response.json()
    escalated = [q for q in queries['data'] if q['metadata'].get('escalated_to_human', False)]
    
    if escalated:
        print(f"📈 {len(escalated)} queries were escalated to humans:")
        for query in escalated[:5]:  # Show top 5
            print(f"- {query['subject']} ({query['query_type']})")
    
    return {
        'success_rate': dashboard['agent_success_rate'],
        'satisfaction': dashboard['avg_customer_satisfaction'],
        'escalated_count': len(escalated)
    }
 
def analyze_agent_effectiveness(agent_id=None):
    """Analyze how effective agents are at resolving queries"""
    headers = {'x-api-key': 'YOUR_API_KEY'}
    
    params = {'limit': 100}
    if agent_id:
        params['agent_id'] = agent_id
    
    response = requests.get(
        'https://api.aloochat.ai/customer-support',
        headers=headers,
        params=params
    )
    
    queries = response.json()
    
    # Analyze resolution methods
    automated = len([q for q in queries['data'] if q['metadata'].get('resolution_method') == 'automated'])
    escalated = len([q for q in queries['data'] if q['metadata'].get('escalated_to_human', False)])
    
    # Analyze customer satisfaction
    satisfaction_scores = [q['metadata'].get('customer_satisfaction', 0) for q in queries['data'] if q['metadata'].get('customer_satisfaction')]
    avg_satisfaction = sum(satisfaction_scores) / len(satisfaction_scores) if satisfaction_scores else 0
    
    # Analyze tools usage
    tools_used = {}
    for query in queries['data']:
        for tool in query['metadata'].get('tools_used', []):
            tools_used[tool] = tools_used.get(tool, 0) + 1
    
    print(f"📊 Agent Effectiveness Analysis:")
    print(f"Total queries: {queries['total']}")
    print(f"Automated resolutions: {automated} ({automated/queries['total']*100:.1f}%)")
    print(f"Human escalations: {escalated} ({escalated/queries['total']*100:.1f}%)")
    print(f"Average satisfaction: {avg_satisfaction:.1f}/5")
    print(f"Most used tools: {dict(sorted(tools_used.items(), key=lambda x: x[1], reverse=True)[:3])}")
    
    return {
        'automated_rate': automated/queries['total']*100,
        'escalation_rate': escalated/queries['total']*100,
        'avg_satisfaction': avg_satisfaction,
        'top_tools': tools_used
    }

Agent Performance Reporting

def generate_agent_performance_report():
    """Generate comprehensive agent performance report"""
    from datetime import datetime, timedelta
    
    headers = {'x-api-key': 'YOUR_API_KEY'}
    
    # Get data for last 30 days
    end_date = datetime.now()
    start_date = end_date - timedelta(days=30)
    
    params = {
        'start_date': start_date.isoformat(),
        'end_date': end_date.isoformat(),
        'granularity': 'week'
    }
    
    # Get analytics and dashboard data
    analytics_response = requests.get(
        'https://api.aloochat.ai/customer-support/analytics',
        headers=headers,
        params=params
    )
    
    dashboard_response = requests.get(
        'https://api.aloochat.ai/customer-support/dashboard',
        headers=headers
    )
    
    analytics = analytics_response.json()
    dashboard = dashboard_response.json()
    
    # Calculate metrics
    total_created = sum(week['queries_created'] for week in analytics['time_series'])
    total_resolved = sum(week['queries_resolved'] for week in analytics['time_series'])
    resolution_rate = (total_resolved / total_created * 100) if total_created > 0 else 0
    
    print(f"🤖 Agent Performance Report (Last 30 Days)")
    print(f"="*50)
    print(f"📈 Volume Metrics:")
    print(f"  Queries Created: {total_created}")
    print(f"  Queries Resolved: {total_resolved}")
    print(f"  Resolution Rate: {resolution_rate:.1f}%")
    print(f"")
    print(f"🎯 Agent Performance:")
    print(f"  Agent-Handled Queries: {dashboard.get('agent_handled_queries', 'N/A')}")
    print(f"  Agent Success Rate: {dashboard.get('agent_success_rate', 'N/A'):.1f}%")
    print(f"  Human Escalations: {dashboard.get('human_escalated_queries', 'N/A')}")
    print(f"  Avg Customer Satisfaction: {dashboard.get('avg_customer_satisfaction', 'N/A'):.1f}/5")
    print(f"")
    print(f"📊 Trends:")
    print(f"  Query Volume: {analytics['trends']['query_volume_trend']}")
    print(f"  Resolution Time: {analytics['trends']['resolution_time_trend']}")
    print(f"")
    print(f"🏆 Top Performing Agents:")
    for agent in dashboard.get('top_performing_agents', [])[:3]:
        print(f"  - {agent['agent_name']}: {agent['success_rate']:.1f}% success, {agent['queries_handled']} queries")
    
    return {
        'volume_metrics': {
            'created': total_created,
            'resolved': total_resolved,
            'resolution_rate': resolution_rate
        },
        'agent_performance': {
            'success_rate': dashboard.get('agent_success_rate'),
            'satisfaction': dashboard.get('avg_customer_satisfaction'),
            'escalation_rate': dashboard.get('human_escalated_queries', 0) / total_created * 100 if total_created > 0 else 0
        },
        'trends': analytics['trends']
    }

Overview Team Notifications