Skip to main content

Clustering

Clustering is a reporting pattern you can build from returned topics across many calls. Start with per-call topics, then group normalized labels in your own application.

AI results are read after a call has completed and recorded audio has been processed. The public API exposes read endpoints for combined AI, transcription, summaries, scoring, and topics. Your integration should store the returned status and payload so the UI can show completed, missing, and failed states separately.

Real Request​

curl -sS https://api.minivoice.eu/v1/calls/call_123/ai-topics \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Real Response​

{
  "count": 3,
  "data": [
    {
      "topic": "Billing",
      "raw_topic": "billing issue",
      "normalized_topic": "Billing",
      "confidence": 0.92
    },
    {
      "topic": "Pricing",
      "raw_topic": "price increase",
      "normalized_topic": "Pricing",
      "confidence": 0.83
    },
    {
      "topic": "Technical Support",
      "raw_topic": "login problem",
      "normalized_topic": "Technical Support",
      "confidence": 0.78
    }
  ]
}

Real Webhook Example​

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "outbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case​

Build a weekly trend report that counts normalized topics across completed calls and links every cluster back to example calls.

Common Failure Case​

{
  "error": {
    "code": "ai_topics_not_found",
    "message": "AI topics not found"
  }
}

Do not hide the call when one AI result is missing. Show the call metadata immediately and let each AI section render its own completed or unavailable state.

Cluster quality

Cluster views are only useful when the sample size is visible. Show how many calls contributed to each group and let users open example calls. Avoid presenting a cluster from one or two calls as a trend.

Start by grouping normalized topics. Later, your own reporting layer can combine topic groups with summaries, outcomes, teams, or DIDs, but the public API source remains the per-call topic result.

Response handling

AI endpoints should be consumed as enrichment, not as the primary call record. Store the call ID, result status, and raw response for each feature your product uses. A completed call can have a completed transcript and a missing score, or a completed summary and no topics. Model those states independently in your UI and data layer.

For dashboards, prefer progressive loading. Show the call metadata first, then render transcript, summary, score, sentiment, and topics as each read succeeds. For automations, branch on explicit result values and status fields instead of assuming every recorded call has the same AI outputs.

Testing​

Place a recorded call with known wording, wait for call.completed, then fetch this endpoint. Save the response as a fixture and test your parser against completed data plus the not-found response shown above.