Call Analysis

Extract structured data from call transcripts using AI to automatically capture sentiment, intents, and outcomes.

Call analysis extracts structured data from call transcripts using AI. Use it to automatically capture customer sentiment, intents, outcomes, and any other data you need.

How It Works

Configure an analysis_plan on your assistant
After each call, the transcript is analyzed
Structured data matching your schema is extracted
Results are included in the end-of-call report webhook

Basic Configuration

Add an analysis plan to your assistant:

curl -X PATCH https://api.hmsovereign.com/api/v1/assistants/ASSISTANT_ID \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis_plan": {
      "structured_data_plan": {
        "enabled": true,
        "schema": {
          "type": "object",
          "properties": {
            "sentiment": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "description": "Customer sentiment score"
            },
            "intent": {
              "type": "string",
              "enum": ["support", "sales", "complaint", "inquiry", "other"]
            },
            "resolved": {
              "type": "boolean",
              "description": "Was the customer issue resolved"
            }
          }
        },
        "messages": [
          {
            "role": "system",
            "content": "Analyze the call transcript and extract structured data according to the schema."
          },
          {
            "role": "user",
            "content": "Schema: {{schema}}\n\nTranscript: {{transcript}}"
          }
        ]
      },
      "min_messages_threshold": 3
    }
  }'

Schema Design

Define the exact data you want to extract using JSON Schema:

{
  "type": "object",
  "properties": {
    "sentiment": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10,
      "description": "Overall customer sentiment (1=very negative, 10=very positive)"
    },
    "primary_intent": {
      "type": "string",
      "enum": ["support", "sales", "complaint", "inquiry", "appointment", "other"],
      "description": "Main reason for the call"
    },
    "topics_discussed": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of main topics covered in the conversation"
    },
    "action_items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "task": { "type": "string" },
          "assigned_to": { "type": "string", "enum": ["assistant", "customer", "other"] }
        }
      }
    },
    "customer_satisfied": {
      "type": "boolean"
    },
    "follow_up_needed": {
      "type": "boolean"
    },
    "summary": {
      "type": "string",
      "description": "Brief summary of the call outcome"
    }
  }
}

Prompt Templates

The messages array defines how the transcript is analyzed. Use placeholders:

Placeholder	Description
`{{schema}}`	Your JSON Schema (auto-injected)
`{{transcript}}`	Full call transcript
`{{ended_reason}}`	Why the call ended

Example Prompts

Basic analysis:

{
  "messages": [
    {
      "role": "system",
      "content": "You are a call analyst. Extract structured data from the call transcript according to the provided schema. Return valid JSON only."
    },
    {
      "role": "user",
      "content": "Schema: {{schema}}\n\nCall transcript:\n{{transcript}}\n\nThe call ended because: {{ended_reason}}"
    }
  ]
}

Detailed analysis with instructions:

{
  "messages": [
    {
      "role": "system",
      "content": "Analyze customer service calls and extract data according to the schema. Guidelines:\n- Sentiment: 1-3 negative, 4-6 neutral, 7-10 positive\n- Only mark resolved=true if the issue was fully addressed\n- Include all mentioned topics, not just the main one"
    },
    {
      "role": "user",
      "content": "Schema:\n{{schema}}\n\nTranscript:\n{{transcript}}\n\nCall ended: {{ended_reason}}\n\nProvide your analysis as JSON."
    }
  ]
}

Minimum Messages Threshold

Set min_messages_threshold to skip analysis for very short calls:

{
  "min_messages_threshold": 5
}

Default: 2 messages
Set higher for meaningful analysis
Analysis is skipped if threshold not met

Receiving Analysis Results

Analysis results are included in the end-of-call report webhook:

{
  "message": {
    "type": "end-of-call-report",
    "duration_seconds": 84,
    "summary": "Customer asked about opening hours...",
    "analysis": {
      "sentiment": 8,
      "primary_intent": "inquiry",
      "topics_discussed": ["opening hours", "location", "parking"],
      "customer_satisfied": true,
      "follow_up_needed": false,
      "summary": "Customer received all requested information."
    }
  }
}

Use Cases

Customer Satisfaction Tracking

{
  "schema": {
    "type": "object",
    "properties": {
      "csat_score": { "type": "integer", "minimum": 1, "maximum": 5 },
      "would_recommend": { "type": "boolean" },
      "pain_points": { "type": "array", "items": { "type": "string" } }
    }
  }
}

Sales Lead Qualification

{
  "schema": {
    "type": "object",
    "properties": {
      "lead_quality": { "type": "string", "enum": ["hot", "warm", "cold"] },
      "budget_mentioned": { "type": "boolean" },
      "timeline": { "type": "string" },
      "decision_maker": { "type": "boolean" },
      "products_interested": { "type": "array", "items": { "type": "string" } }
    }
  }
}

Support Ticket Classification

{
  "schema": {
    "type": "object",
    "properties": {
      "category": { "type": "string", "enum": ["billing", "technical", "account", "product", "other"] },
      "priority": { "type": "string", "enum": ["low", "medium", "high", "urgent"] },
      "resolution_status": { "type": "string", "enum": ["resolved", "escalated", "pending", "unresolved"] },
      "root_cause": { "type": "string" }
    }
  }
}

Best Practices

Keep schemas focused - Extract only what you'll actually use
Use enums - Predefined values make data more consistent
Add descriptions - Help the AI understand what you want
Test prompts - Refine your prompts based on actual results
Set appropriate thresholds - Skip analysis for calls too short to be meaningful

See Analysis Templates and End of Call Report Webhook for complete details.

On this page