Documentation

Get Started with Customer Support AI Monitor

Everything you need to integrate CSAT tracking, monitor escalations, and prove ROI from your Customer Support AI chatbot

Quick Start

Get up and running in 60 seconds

Configuration

Customize your monitoring setup

Examples

Real-world integration examples

Quick Start

1. Get Your API Key

Sign up at Customer Support AI Monitor and get your API key from the dashboard. API keys start with amo_ prefix.

2. Track a Conversation

Send conversation data to our API after each customer interaction:

# Track a customer support conversation
curl -X POST https://api.csaimonitor.com/api/v1/conversations \
  -H "Content-Type: application/json" \
  -H "X-API-Key: amo_your_api_key_here" \
  -d '{
    "conversation_id": "ticket_12345",
    "platform": "zendesk",
    "messages": [
      {"sender_type": "customer", "content": "How do I reset my password?"},
      {"sender_type": "ai", "content": "Go to Settings > Security > Reset Password."}
    ],
    "csat_score": 5,
    "escalated": false,
    "ai_handled": true,
    "topic": "password_reset"
  }'

3. View Your Metrics

Get CSAT scores, escalation rates, and cost savings from your dashboard:

# Get dashboard metrics (last 24 hours)
curl https://api.csaimonitor.com/api/v1/cs-metrics/dashboard \
  -H "X-API-Key: amo_your_api_key_here"

# Get metrics for last 7 days (168 hours)
curl https://api.csaimonitor.com/api/v1/cs-metrics/dashboard?time_range=168 \
  -H "X-API-Key: amo_your_api_key_here"

You're all set!

Your conversations are now being tracked. Check your dashboard to see CSAT scores, escalation patterns, and ROI metrics.

API Reference

Authentication

All API requests require your API key in the header:

X-API-Key: amo_your_api_key_here

POST /api/v1/conversations

Track a customer support conversation. This is the main endpoint for sending data.

{
  // Required fields
  "conversation_id": "ticket_12345",  // Unique conversation ID
  "platform": "zendesk",              // zendesk, freshdesk, custom, sdk
  "messages": [                       // Array of messages
    {
      "sender_type": "customer",      // customer, ai, human_agent
      "content": "Message text",
      "timestamp": "2026-01-15T10:30:00Z"
    }
  ],

  // Customer Support metrics (optional but recommended)
  "csat_score": 5,                    // 1-5 rating
  "sentiment": "positive",            // positive, neutral, negative, frustrated
  "escalated": false,                 // Was escalated to human?
  "escalation_reason": "complex_issue",
  "first_contact_resolution": true,
  "resolution_time_seconds": 120,

  // AI tracking (optional)
  "ai_handled": true,                 // Was handled by AI?
  "ai_agent_id": "support_bot_v2",
  "ai_confidence_score": 0.95,

  // Cost tracking (optional)
  "cost_usd": 0.02,                   // AI cost for this conversation
  "estimated_human_cost_usd": 5.00,   // What human would cost

  // Classification (optional)
  "topic": "password_reset",
  "customer_id": "cust_789"
}

GET /api/v1/cs-metrics/dashboard

Get aggregated Customer Support metrics.

# Query parameters
?time_range=24    # Hours to look back (default: 24)
                  # Examples: 24 (1 day), 168 (7 days), 720 (30 days)

# Response
{
  "success": true,
  "metrics": {
    "total_conversations": 150,
    "ai_handled_conversations": 120,
    "human_handled_conversations": 30,
    "escalated_conversations": 18,
    "avg_csat_score": 4.2,
    "avg_ai_csat_score": 4.1,
    "avg_human_csat_score": 4.5,
    "escalation_rate": 12.0,
    "first_contact_resolution_rate": 85.0,
    "total_ai_cost": 24.50,
    "total_estimated_human_cost": 750.00,
    "cost_savings": 725.50,
    "top_topics": [
      {"topic": "billing", "count": 45, "escalation_rate": 8.9},
      {"topic": "password_reset", "count": 32, "escalation_rate": 3.1}
    ]
  }
}

Other Endpoints

EndpointDescription
GET /api/v1/conversationsList conversations with filters
GET /api/v1/cs-metrics/escalation-patternsGet escalation patterns by topic
GET /api/v1/cs-metrics/cost-analysisGet ROI and cost analysis
GET /api/v1/cs-metrics/csat-trendsGet CSAT trends over time
GET /api/v1/conversations/knowledge-gapsGet unanswered questions

Integration Examples

Python Integration

Track conversations from your Python application:

import requests
import openai

API_KEY = "amo_your_api_key_here"
API_URL = "https://api.csaimonitor.com/api/v1"

def track_conversation(conversation_id, messages, csat_score=None, escalated=False):
    """Send conversation data to CS AI Monitor"""
    response = requests.post(
        f"{API_URL}/conversations",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "conversation_id": conversation_id,
            "platform": "custom",
            "messages": messages,
            "csat_score": csat_score,
            "escalated": escalated,
            "ai_handled": True
        }
    )
    return response.json()

# Example: Track after AI handles a support query
def handle_support_query(user_message):
    # Your AI logic
    ai_response = openai.chat.completions.create(
        model="gpt-4",
        messages=[{"role": "user", "content": user_message}]
    ).choices[0].message.content
    
    # Track the conversation
    track_conversation(
        conversation_id=f"conv_{int(time.time())}",
        messages=[
            {"sender_type": "customer", "content": user_message},
            {"sender_type": "ai", "content": ai_response}
        ],
        csat_score=5
    )
    
    return ai_response

Node.js Integration

Track conversations from your Node.js application:

const axios = require('axios');

const API_KEY = 'amo_your_api_key_here';
const API_URL = 'https://api.csaimonitor.com/api/v1';

async function trackConversation(data) {
  const response = await axios.post(
    `${API_URL}/conversations`,
    {
      conversation_id: data.conversationId,
      platform: 'custom',
      messages: data.messages,
      csat_score: data.csatScore,
      escalated: data.escalated || false,
      ai_handled: true,
      topic: data.topic
    },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Example usage
await trackConversation({
  conversationId: 'ticket_123',
  messages: [
    { sender_type: 'customer', content: 'How do I cancel?' },
    { sender_type: 'ai', content: 'Go to Settings > Subscription...' }
  ],
  csatScore: 4,
  topic: 'cancellation'
});

Zendesk Integration

Webhook Setup

Configure Zendesk to send ticket updates automatically:

  1. Go to Zendesk Admin Center → Apps and integrations → Webhooks
  2. Click Create webhook
  3. Set the endpoint URL from your CS AI Monitor dashboard
  4. Select events: Ticket Created, Ticket Updated, Ticket Solved
  5. Add your webhook secret for signature verification
# Webhook URL format
https://api.csaimonitor.com/api/v1/webhooks/zendesk?org_id=YOUR_ORG_ID

# Zendesk sends ticket data automatically:
{
  "ticket_id": "12345",
  "ticket": {
    "id": 12345,
    "subject": "Password reset help",
    "status": "solved",
    "satisfaction_rating": { "score": "good" },
    "tags": ["ai_handled", "password"],
    "comments": [...]
  }
}

Manual Zendesk Integration

If you prefer to track conversations manually from your Zendesk app:

import requests

def track_zendesk_ticket(ticket):
    """Track a Zendesk ticket as a conversation"""
    
    # Convert Zendesk comments to messages
    messages = []
    for comment in ticket['comments']:
        sender = 'ai' if comment.get('via', {}).get('channel') == 'api' else 'customer'
        messages.append({
            'sender_type': sender,
            'content': comment['body'],
            'timestamp': comment['created_at']
        })
    
    # Map Zendesk satisfaction to CSAT score
    csat_map = {'good': 5, 'offered': 3, 'bad': 1}
    rating = ticket.get('satisfaction_rating', {})
    csat_score = csat_map.get(rating.get('score'), None)
    
    # Track the conversation
    response = requests.post(
        'https://api.csaimonitor.com/api/v1/conversations',
        headers={
            'X-API-Key': 'amo_your_api_key_here',
            'Content-Type': 'application/json'
        },
        json={
            'conversation_id': f"zendesk_{ticket['id']}",
            'platform': 'zendesk',
            'platform_ticket_id': str(ticket['id']),
            'messages': messages,
            'csat_score': csat_score,
            'escalated': 'escalated' in ticket.get('tags', []),
            'ai_handled': 'ai_handled' in ticket.get('tags', []),
            'topic': ticket.get('subject', 'general')
        }
    )
    return response.json()

Get Dashboard Metrics

Fetch metrics to display in your own dashboard:

import requests

def get_cs_metrics(time_range_hours=168):
    """Get Customer Support metrics for the last N hours"""
    response = requests.get(
        'https://api.csaimonitor.com/api/v1/cs-metrics/dashboard',
        headers={'X-API-Key': 'amo_your_api_key_here'},
        params={'time_range': time_range_hours}
    )
    data = response.json()
    metrics = data['metrics']
    
    print(f"Total conversations: {metrics['total_conversations']}")
    print(f"AI handled: {metrics['ai_handled_conversations']}")
    print(f"Average CSAT: {metrics['avg_csat_score']:.1f}/5.0")
    print(f"Escalation rate: {metrics['escalation_rate']:.1f}%")
    print(f"Cost savings: ${metrics['cost_savings']:.2f}")
    
    return metrics

# Get last 7 days of metrics
metrics = get_cs_metrics(168)

Best Practices

Track After Each Conversation

Send conversation data immediately after each AI interaction for real-time metrics. Don't batch conversations - track them as they happen.

Include Accurate Cost Data

Provide actual LLM costs for precise ROI calculations. This helps prove the value of your AI to leadership.

{
  "cost_usd": 0.02,              // Actual AI cost
  "estimated_human_cost_usd": 5  // What human would cost (~$25/hr)
}

Classify Topics Consistently

Use consistent topic names to get meaningful analytics. This helps identify which topics need AI improvement.

// Good - consistent naming
"topic": "billing"
"topic": "password_reset"
"topic": "account_cancellation"

// Bad - inconsistent
"topic": "Billing question"
"topic": "billing-issue"
"topic": "BILLING"

Track CSAT When Available

Include customer satisfaction scores whenever available. CSAT is the key metric for proving AI quality to stakeholders.

Mark Escalations Accurately

Always set escalated: true when a conversation is handed to a human. Include the reason to identify patterns.

{
  "escalated": true,
  "escalation_reason": "customer_requested_human"
  // Other reasons: "complex_issue", "ai_unsure", "sensitive_topic"
}

Handle Errors Gracefully

Implement retry logic with exponential backoff. If the API is down, queue conversations and send later. Never let tracking failures affect your customer experience.

Need Help?

Our team is here to help you get the most out of Customer Support AI Monitor.

Contact SupportAbout Us