shopcall/VAPI_INTEGRATION.md

VAPI Integration Documentation

Overview

ShopCall.ai integrates with VAPI (Voice AI Platform) to receive and store call data from AI-powered phone conversations. This integration allows the system to track call logs, transcripts, recordings, and analytics from VAPI calls.

Architecture

Components

1. VAPI Webhook Endpoint (/functions/v1/vapi-webhook)

   • Receives POST requests from VAPI
   • Validates and processes end-of-call reports
   • Stores call data in the database

2. Database Schema (call_logs table)

   • Stores call metadata, transcripts, and analytics
   • Includes VAPI-specific fields for messages, analysis, and recording URLs

3. API Endpoint (/api/call-logs)

   • Retrieves call logs for authenticated users
   • Transforms data for frontend display

4. WebUI (/call-logs page)

   • Displays call logs in a table format
   • Shows detailed call information including transcripts and recordings

Database Schema

New Fields in call_logs Table

Field	Type	Description
vapi_call_id	TEXT	Unique identifier from VAPI for this call
messages	JSONB	Array of conversation messages (bot/user/system/tool_calls)
analysis	JSONB	VAPI analysis object (summary, successEvaluation)
stereo_recording_url	TEXT	URL to stereo recording from VAPI
pcap_url	TEXT	URL to SIP packet capture file
log_url	TEXT	URL to VAPI call logs
vapi_timestamp	BIGINT	VAPI event timestamp in milliseconds

Indexes

• idx_call_logs_vapi_call_id - Fast lookups by VAPI call ID
• idx_call_logs_vapi_timestamp - Time-based queries

VAPI Webhook Configuration

Webhook URL

https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1/vapi-webhook

Webhook Events

The integration listens for end-of-call-report events from VAPI.

Expected Payload Structure

{
  "message": {
    "timestamp": 1763633517714,
    "type": "end-of-call-report",
    "analysis": {
      "summary": "Call summary text",
      "successEvaluation": "true"
    },
    "artifact": {
      "messages": [
        {
          "role": "bot|user|system|tool_calls|tool_call_result",
          "message": "Message text",
          "time": 1763633305414,
          "endTime": 1763633327672,
          "secondsFromStart": 0.486,
          "duration": 270
        }
      ],
      "transcript": "Full conversation transcript",
      "recordingUrl": "https://storage.vapi.ai/...",
      "stereoRecordingUrl": "https://storage.vapi.ai/...",
      "pcapUrl": "https://storage.vapi.ai/...",
      "logUrl": "https://calllogs.vapi.ai/..."
    },
    "call": {
      "id": "unique-call-id",
      "assistantId": "assistant-id",
      "phoneNumberId": "phone-number-id",
      "customerId": "customer-phone-number",
      "costBreakdown": {
        "stt": 0.0012,
        "llm": 0.0034,
        "tts": 0.0023,
        "twilio": 0.0050,
        "total": 0.0119
      }
    }
  }
}

Data Mapping

VAPI → call_logs

VAPI Field	call_logs Field
message.call.id	vapi_call_id
message.timestamp	vapi_timestamp, started_at, ended_at
message.artifact.messages	messages
message.analysis	analysis
message.analysis.summary	summary
message.artifact.transcript	transcript
message.artifact.recordingUrl	recording_url
message.artifact.stereoRecordingUrl	stereo_recording_url
message.artifact.pcapUrl	pcap_url
message.artifact.logUrl	log_url
message.call.assistantId	assistant_id
message.call.phoneNumberId	phone_number_id
message.call.customerId	customer_number
message.call.costBreakdown.*	cost_stt, cost_llm, cost_tts, cost_twilio, cost_total

Call Outcome Mapping

• analysis.successEvaluation = "true" → call_outcome = "resolved"
• analysis.successEvaluation = "false" → call_outcome = "not_interested"
• No evaluation → call_outcome = "pending"

Duration Calculation

Duration is calculated from the last message's secondsFromStart field.

WebUI Features

Call Logs Table

Displays:

• Call time
• Customer phone number (masked for privacy)
• Intent/Summary
• Outcome (color-coded)
• Duration
• Sentiment (based on successEvaluation)
• Cost

Call Details Modal

Shows:

• Full conversation transcript with timestamps
• Individual messages (customer/assistant)
• Call summary and success evaluation
• Recording playback links (mono and stereo)
• Call analytics and metadata
• Link to VAPI call logs

API Endpoints

POST /functions/v1/vapi-webhook

Purpose: Receive VAPI webhooks

Authentication: None (service-level endpoint)

Request Body: VAPI webhook payload (JSON)

Response:

{
  "status": "success",
  "call_log_id": "uuid",
  "message": "Call log stored successfully"
}

GET /api/call-logs

Purpose: Retrieve call logs for authenticated user

Authentication: Bearer token (required)

Response:

{
  "success": true,
  "call_logs": [
    {
      "id": "uuid",
      "time": "2025-11-20 10:30:45",
      "customer": "...xxx-1234",
      "intent": "Customer inquiry",
      "outcome": "resolved",
      "duration": "3:25",
      "sentiment": "Positive",
      "cost": "$0.0119",
      "outcomeColor": "text-green-500",
      "sentimentColor": "text-green-500",
      "fullData": { /* complete call log object */ }
    }
  ]
}

Security

Webhook Security

Currently, the webhook endpoint accepts all POST requests. For production, consider:

1. VAPI Signature Verification: Validate VAPI webhook signatures
2. IP Allowlisting: Restrict to VAPI IP addresses
3. Rate Limiting: Prevent abuse

Data Privacy

• Customer phone numbers are masked in the UI (...xxx-1234)
• Full phone numbers stored in database for analytics
• Call recordings stored externally (VAPI)
• Transcripts contain PII - handle according to GDPR

Deployment

Database Migration

# Migration is already applied
# File: /supabase/migrations/20251120_vapi_integration.sql

Edge Functions

# Deploy VAPI webhook handler
supabase functions deploy vapi-webhook --project-ref ztklqodcdjeqpsvhlpud

# Deploy updated API endpoint
supabase functions deploy api --project-ref ztklqodcdjeqpsvhlpud

Environment Variables

Required in Supabase Edge Functions:

• SUPABASE_URL - Supabase project URL
• SUPABASE_SERVICE_ROLE_KEY - Service role key for database access

Testing

Manual Testing

1. Test Webhook Endpoint:

   curl -X POST https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1/vapi-webhook \
   -H "Content-Type: application/json" \
   -d @test-payload.json
   

2. Test API Endpoint:

   curl https://ztklqodcdjeqpsvhlpud.supabase.co/functions/v1/api/call-logs \
   -H "Authorization: Bearer YOUR_TOKEN"
   

3. Test WebUI:

   • Navigate to /call-logs
   • Verify calls are displayed
   • Click "Details" to view full call information

Sample Test Payload

See message object in the VAPI webhook payload example above.

Troubleshooting

Common Issues

1. Webhook not receiving data

   • Verify VAPI webhook URL configuration
   • Check Supabase Edge Function logs
   • Ensure end-of-call-report event is enabled

2. Call logs not appearing in UI

   • Check browser console for errors
   • Verify API endpoint returns data
   • Ensure user authentication is valid

3. Missing transcript or messages

   • Check VAPI payload structure
   • Verify artifact.messages array exists
   • Confirm transcript generation in VAPI

Logs

View Edge Function logs:

# Via Supabase Dashboard
https://supabase.com/dashboard/project/ztklqodcdjeqpsvhlpud/functions

# Via CLI
supabase functions logs vapi-webhook

Future Enhancements

Planned Features

1. Real-time Updates: WebSocket integration for live call updates
2. Search and Filtering: Advanced search by customer, outcome, date range
3. Analytics Dashboard: Call statistics, sentiment analysis, trends
4. Export Functionality: CSV/PDF export of call logs
5. Webhook Signature Verification: Enhanced security
6. User Assignment: Link calls to specific user_id
7. Call Tagging: Custom tags for call categorization

Optional Improvements

1. Audio Playback: In-browser audio player for recordings
2. Sentiment Analysis: AI-powered sentiment detection
3. Call Scoring: Automated quality scoring
4. Integration with CRM: Sync call data to external systems
5. Notification System: Alerts for important calls

Related Issues

• Issue #104: Initial VAPI integration implementation

References

• VAPI Documentation
• Supabase Edge Functions
• Supabase Database