playbooks

home / skills / gracebotly / flowetic-app / vapi

vapi skill

/workspace/skills/vapi

This skill maps Vapi voice events to dashboard templates, enabling consistent analytics dashboards from call transcripts, durations, status, and cost data.

npx playbooks add skill gracebotly/flowetic-app --skill vapi

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
2.8 KB
---
name: vapi
version: 2.0.0
platformType: vapi
description: Mapping guidance for Vapi voice AI events. Covers call metrics, assistant performance, cost tracking, and transcript handling. Use for any Vapi-connected dashboard generation or editing task.
tags:
  - platform
  - vapi
  - voice
  - analytics
metadata:
  author: getflowetic
  phase-scope: all
lastUpdated: 2026-02-25
---

# Vapi Platform Skill

## Overview
Vapi is a voice AI platform for building phone agents. Users connect Vapi assistants to Getflowetic to monitor call performance, track costs, and analyze conversation outcomes.

## Vocabulary
- **call**: A single voice interaction between an assistant and a caller
- **assistant**: A configured Vapi voice agent with a system prompt, model, and voice
- **ended_reason**: Why the call terminated (hangup, voicemail, error, silence-timeout, max-duration)
- **cost**: Per-call cost in USD based on duration + model usage
- **transcript**: Full text of the conversation
- **status**: Call outcome — `ended` (success) or other values (failure)

## Key Metrics for Dashboards
- **Call Volume**: Total calls over time — trend chart on started_at
- **Success Rate**: Percentage of calls with status=success — hero stat
- **Avg Duration**: Average call length in ms — supporting metric card
- **Cost per Call**: Total cost divided by call count — supporting metric
- **Assistant Breakdown**: Calls per assistant — pie chart on assistant_name/workflow_name

## Event Field Mapping
The Vapi import route normalizes call data into the standard event schema. These are the fields that appear in `event.state`:

| Event Field | Semantic Type | Dashboard Use |
|-------------|--------------|--------------|
| workflow_id | identifier | Maps to assistant_id — count only |
| workflow_name | dimension | Maps to assistant name — breakdown charts |
| execution_id | surrogate_key | Maps to call_id — "Total Calls" KPI |
| status | dimension | Success rate percentage — hero stat |
| duration_ms | measure (avg) | "Avg Call Duration" metric card |
| started_at | time_dimension | Timeseries trend axis |
| ended_at | time_dimension | Detail only |
| platform | constant | Always "vapi" — skip |

These fields also appear in `event.labels`:
- assistant_id, assistant_name, call_id, status

## Dashboard Templates
- **voice-analytics**: Call volume trend, success rate, avg duration, assistant breakdown
- **assistant-performance**: Per-assistant comparison with call counts and durations
- **cost-tracker**: Cost trends over time, cost per call, total spend

## Mapping Heuristics (Legacy Aliases)
These field name variations should resolve to the canonical names above:
- duration: call_duration_seconds | duration | call_length → duration_ms
- status: status | call_status | outcome → status
- cost: cost_usd | cost | price → cost

Overview

This skill provides mapping guidance to convert Vapi voice event fields into dashboard-ready templates. It standardizes common voice event vocabulary (call, transcript, duration, cost, status) and supplies heuristics to map inconsistent field names to canonical dashboard properties. The output focuses on a voice-analytics template for quick integration into reporting pipelines.

How this skill works

The skill inspects incoming Vapi voice event payloads and applies a small set of heuristics to resolve field name variations into canonical properties: duration, status, and cost. It outputs a normalized object matching the voice-analytics template, preserving raw fields for auditability. Use the mapping rules to transform events before storing, aggregating, or feeding visualization layers.

When to use it

  • Ingesting heterogeneous Vapi voice event streams with inconsistent field names.
  • Preparing data for a voice-analytics dashboard that expects canonical fields.
  • Normalizing events before cost, duration, or status-based aggregation.
  • Building ETL pipelines where downstream systems require stable property names.
  • Validating or enriching call records prior to long-term storage.

Best practices

  • Apply the mapping heuristics early in the pipeline to avoid branching logic downstream.
  • Keep original event fields alongside canonical fields for traceability and debugging.
  • Treat mappings as configurable rules so you can extend or override heuristics for edge cases.
  • Validate numeric conversions (e.g., duration, cost) and handle missing or malformed values explicitly.
  • Log mapping decisions at a coarse level to monitor changes in upstream schemas.

Example use cases

  • Normalize events where call duration appears as call_duration_seconds, duration, or call_length into a single duration property.
  • Map different status fields (status, call_status, outcome) to a canonical status used by the dashboard.
  • Aggregate daily call cost by mapping cost_usd, cost, or price into cost and summing per call.
  • Feed normalized voice-analytics objects into a real-time metrics pipeline for live dashboards.
  • Create alerts based on normalized status transitions (e.g., FAILED, DROPPED, COMPLETED).

FAQ

What happens if a field is missing?

The skill leaves the canonical field null or undefined and preserves raw payloads; best practice is to apply default values or flag records for review.

Can I extend the mapping rules?

Yes. Treat the heuristics as configurable; add new aliases or override mappings to match your upstream schema.