qualia-framework 2.2.0 → 2.4.0

package/framework/skills/voice-agent/SKILL.md

@@ -1,24 +1,26 @@
 ---
 name: voice-agent
-description: Build complete voice AI agents - design conversational flow, create VAPI assistant, integrate Supabase, deploy. Full voice agent development.
-tags: [voice, vapi, ai-agent, supabase, elevenlabs]
+description: "Build complete voice AI agents with Retell AI + ElevenLabs — design conversational flow, create Retell agent, integrate Supabase backend, configure webhooks, deploy and test. Use this skill whenever the user says 'build voice agent', 'create voice assistant', 'voice AI', 'phone bot', 'retell agent', or wants to build any voice-based AI system. Also trigger on 'retell', 'elevenlabs', 'voice webhook', 'call agent'."
+tags: [voice, retell, elevenlabs, ai-agent, supabase]
 ---
 
 # Voice Agent Builder
 
-Build complete voice AI agents from design to deployment.
+Build complete voice AI agents from design to deployment using Retell AI (call orchestration) + ElevenLabs (TTS/voice cloning) + Supabase (backend).
+
+**Announce at start:** "Activating voice agent builder. Let me set up your Retell AI + ElevenLabs agent."
 
 ## Pipeline
 
 ```
 1. Design Conversation Flow
-       ↓
-2. Create VAPI Assistant
-       ↓
+       |
+2. Create Retell Agent
+       |
 3. Setup Supabase Backend
-       ↓
+       |
 4. Configure Webhooks
-       ↓
+       |
 5. Deploy & Test
 ```
 
@@ -29,375 +31,1269 @@ Say: "build voice agent for [use case]"
 Example: "build voice agent for appointment scheduling"
 
 I will:
-1. Design the conversation flow
-2. Create VAPI assistant configuration
-3. Set up Supabase tables for state
-4. Configure webhooks
-5. Deploy and test
+1. Design the conversation flow (state machine + flow diagram)
+2. Create Retell agent with ElevenLabs voice
+3. Set up Supabase tables (call_logs, agent_state, domain tables)
+4. Build webhook handler as Supabase Edge Function
+5. Assign phone number and test
+
+## Environment Variables Needed
+
+```env
+# Retell AI
+RETELL_API_KEY=key_...
+
+# ElevenLabs
+ELEVENLABS_API_KEY=xi_...
+
+# Supabase (auto-available in Edge Functions)
+SUPABASE_URL=https://xxx.supabase.co
+SUPABASE_SERVICE_ROLE_KEY=eyJ...
+
+# LLM (if using OpenRouter for custom LLM)
+OPENROUTER_API_KEY=sk-or-...
+```
+
+---
 
 ## Stage 1: Design Conversation Flow
 
 ### Flow Diagram
+
 ```
-┌──────────────────┐
-│   Call Starts    │
-└────────┬─────────┘
-         ↓
-┌──────────────────┐
-│    Greeting      │
-│ "Hello, how can  │
-│  I help you?"    │
-└────────┬─────────┘
-         ↓
-┌──────────────────┐
-│  Intent Detection │
-│ - Book appointment│
-│ - Check status    │
-│ - Other inquiry   │
-└────────┬─────────┘
-         ↓
-   ┌─────┴─────┐
-   ↓           ↓
-┌──────┐   ┌──────┐
-│ Book │   │ Help │
-└──────┘   └──────┘
++--------------------+
+|   Call Starts      |
++--------+-----------+
+         |
++--------v-----------+
+|     Greeting        |
+| "Hello, thanks for  |
+|  calling. How can   |
+|  I help you?"       |
++--------+-----------+
+         |
++--------v-----------+
+|  Intent Detection   |
+| - Book appointment  |
+| - Check status      |
+| - General inquiry   |
+| - Transfer to human |
++--------+-----------+
+         |
+   +-----+------+------+
+   |            |      |
++--v---+  +----v--+ +-v--------+
+| Book |  | Check | | Transfer |
++--+---+  +----+--+ +----------+
+   |            |
++--v-----------v--+
+|    Confirm &     |
+|    End Call      |
++-----------------+
 ```
 
 ### State Machine
+
 ```typescript
-const conversationStates = {
+type ConversationState =
+  | 'GREETING'
+  | 'INTENT_DETECTION'
+  | 'BOOKING'
+  | 'COLLECT_DATE'
+  | 'COLLECT_TIME'
+  | 'COLLECT_NAME'
+  | 'CONFIRM_BOOKING'
+  | 'STATUS_CHECK'
+  | 'GENERAL_INQUIRY'
+  | 'TRANSFER'
+  | 'FAREWELL';
+
+const conversationFlow: Record<ConversationState, {
+  next: ConversationState[];
+  actions: string[];
+}> = {
   GREETING: {
     next: ['INTENT_DETECTION'],
-    actions: ['playGreeting']
+    actions: ['playGreeting'],
   },
   INTENT_DETECTION: {
-    next: ['BOOKING', 'STATUS_CHECK', 'TRANSFER'],
-    actions: ['detectIntent']
+    next: ['BOOKING', 'STATUS_CHECK', 'GENERAL_INQUIRY', 'TRANSFER'],
+    actions: ['detectIntent'],
   },
   BOOKING: {
-    next: ['COLLECT_DATE', 'COLLECT_TIME', 'CONFIRM'],
-    actions: ['startBooking']
+    next: ['COLLECT_DATE'],
+    actions: ['startBookingFlow'],
+  },
+  COLLECT_DATE: {
+    next: ['COLLECT_TIME'],
+    actions: ['askForDate', 'validateDate'],
+  },
+  COLLECT_TIME: {
+    next: ['COLLECT_NAME'],
+    actions: ['askForTime', 'checkAvailability'],
+  },
+  COLLECT_NAME: {
+    next: ['CONFIRM_BOOKING'],
+    actions: ['askForName'],
+  },
+  CONFIRM_BOOKING: {
+    next: ['FAREWELL', 'COLLECT_DATE'], // retry if rejected
+    actions: ['readBackDetails', 'bookAppointment'],
+  },
+  STATUS_CHECK: {
+    next: ['FAREWELL', 'INTENT_DETECTION'],
+    actions: ['lookupAppointment', 'readStatus'],
+  },
+  GENERAL_INQUIRY: {
+    next: ['FAREWELL', 'INTENT_DETECTION'],
+    actions: ['answerQuestion'],
+  },
+  TRANSFER: {
+    next: ['FAREWELL'],
+    actions: ['transferToHuman'],
+  },
+  FAREWELL: {
+    next: [],
+    actions: ['endCall'],
   },
-  // ...
 };
 ```
 
-## Stage 2: Create VAPI Assistant
+### System Prompt Template
 
-### Assistant Configuration
-```typescript
-const assistant = {
-  name: "Appointment Scheduler",
-  model: {
-    provider: "anthropic",
-    model: "claude-3-5-sonnet-20241022",
-    temperature: 0.7,
-    systemPrompt: `You are a friendly appointment scheduling assistant.
-Your job is to help callers book appointments.
+```
+You are a friendly and professional [ROLE] for [COMPANY].
+Your job is to help callers [PRIMARY_TASK].
 
 ## Capabilities
-- Book new appointments
-- Check existing appointments
-- Reschedule appointments
-- Answer questions about services
-
-## Conversation Flow
-1. Greet the caller warmly
-2. Ask how you can help
-3. Collect necessary information
-4. Confirm the action
-5. End the call politely
-
-## Important Rules
-- Always confirm before booking
-- Validate dates and times
-- Collect caller's phone for confirmation
-- Be concise but friendly`
+- [Capability 1]
+- [Capability 2]
+- [Capability 3]
+
+## Conversation Rules
+1. Keep responses to 1-2 sentences. Callers hate long monologues.
+2. Always confirm critical info back to the caller before acting.
+3. If unsure, ask a clarifying question rather than guessing.
+4. Never make up information. If you don't know, say so.
+5. Be warm but efficient — respect the caller's time.
+6. If the caller wants a human, transfer immediately. Don't argue.
+
+## Available Tools
+- book_appointment: Book a new appointment
+- check_availability: Check open time slots
+- lookup_appointment: Find existing appointment by phone
+
+## Escalation
+If the caller is frustrated, angry, or asks for a manager:
+→ Apologize briefly, then transfer to a human operator.
+```
+
+---
+
+## Stage 2: Create Retell Agent
+
+### Agent Configuration
+
+```typescript
+interface RetellAgentConfig {
+  agent_name: string;
+  voice_id: string;                    // ElevenLabs voice ID
+  response_engine: {
+    type: 'retell-llm';
+    llm_id: string;                    // Created separately via Retell LLM API
+  } | {
+    type: 'custom-llm';
+    llm_websocket_url: string;         // Your own LLM WebSocket endpoint
+  };
+  language: string;                    // 'en-US', 'ar', 'el', etc.
+  voice_temperature: number;           // 0-2, controls voice expressiveness
+  voice_speed: number;                 // 0.5-2, speech rate
+  responsiveness: number;              // 0-1, how quickly agent responds
+  interruption_sensitivity: number;    // 0-1, how easily caller can interrupt
+  enable_backchannel: boolean;         // "uh huh", "I see" filler words
+  backchannel_frequency: number;       // 0-1
+  reminder_trigger_ms: number;         // Silence before nudge (default 10000)
+  reminder_max_count: number;          // Max nudges before ending (default 2)
+  ambient_sound: string | null;        // 'coffee-shop', 'convention-hall', 'summer-outdoor', 'mountain-spring', 'static-noise', 'call-center' or null
+  begin_message: string | null;        // First message (null = wait for caller)
+  webhook_url: string;                 // Your webhook endpoint
+  post_call_analysis_data: Array<{
+    type: 'string' | 'enum' | 'boolean';
+    name: string;
+    description: string;
+    examples?: string[];
+    options?: string[];
+  }>;
+}
+```
+
+### Create Agent via Retell API
+
+```typescript
+// Create the Retell LLM first (defines the brain)
+const llmResponse = await fetch('https://api.retellai.com/v2/create-retell-llm', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
   },
-  voice: {
-    provider: "11labs",
-    voiceId: "21m00Tcm4TlvDq8ikWAM", // Rachel
-    stability: 0.5,
-    similarityBoost: 0.75
+  body: JSON.stringify({
+    model: 'claude-3-5-sonnet',        // Or use 'gpt-4o', 'claude-3-5-haiku'
+    general_prompt: `You are a friendly appointment scheduling assistant for Qualia Solutions.
+Your job is to help callers book, check, or reschedule appointments.
+
+Rules:
+- Keep responses to 1-2 sentences max
+- Always confirm dates and times back to the caller
+- Be warm but efficient`,
+    begin_message: 'Hello! Thanks for calling Qualia Solutions. How can I help you today?',
+    general_tools: [
+      {
+        type: 'end_call',
+        name: 'end_call',
+        description: 'End the call when the conversation is complete',
+      },
+      {
+        type: 'custom',
+        name: 'book_appointment',
+        description: 'Book a new appointment for the caller',
+        parameters: {
+          type: 'object',
+          properties: {
+            date: { type: 'string', description: 'Appointment date in YYYY-MM-DD format' },
+            time: { type: 'string', description: 'Appointment time in HH:MM format (24h)' },
+            service: { type: 'string', description: 'Type of service requested' },
+            caller_name: { type: 'string', description: 'Full name of the caller' },
+          },
+          required: ['date', 'time', 'service', 'caller_name'],
+        },
+        url: 'https://YOUR_PROJECT.supabase.co/functions/v1/retell-tool-handler',
+        speak_during_execution: true,
+        speak_after_execution: true,
+        execution_message_description: 'Let the caller know you are checking availability and booking their appointment.',
+      },
+      {
+        type: 'custom',
+        name: 'check_availability',
+        description: 'Check available appointment slots for a given date',
+        parameters: {
+          type: 'object',
+          properties: {
+            date: { type: 'string', description: 'Date to check in YYYY-MM-DD format' },
+          },
+          required: ['date'],
+        },
+        url: 'https://YOUR_PROJECT.supabase.co/functions/v1/retell-tool-handler',
+        speak_during_execution: true,
+        speak_after_execution: true,
+        execution_message_description: 'Let the caller know you are checking available times.',
+      },
+    ],
+    states: [
+      {
+        name: 'greeting',
+        state_prompt: 'Greet the caller warmly and ask how you can help.',
+        transitions: [
+          {
+            name: 'booking_intent',
+            description: 'Caller wants to book an appointment',
+            destination: 'collect_info',
+          },
+          {
+            name: 'check_intent',
+            description: 'Caller wants to check an existing appointment',
+            destination: 'status_check',
+          },
+          {
+            name: 'other_intent',
+            description: 'Caller has a general question',
+            destination: 'general_help',
+          },
+        ],
+      },
+      {
+        name: 'collect_info',
+        state_prompt: 'Collect the date, time, service type, and caller name. Use check_availability before booking. Then use book_appointment to confirm.',
+        transitions: [
+          {
+            name: 'booking_complete',
+            description: 'Appointment has been booked successfully',
+            destination: 'farewell',
+          },
+        ],
+      },
+      {
+        name: 'status_check',
+        state_prompt: 'Ask for the caller phone number or name to look up their appointment.',
+        transitions: [
+          {
+            name: 'status_done',
+            description: 'Status has been communicated to caller',
+            destination: 'farewell',
+          },
+        ],
+      },
+      {
+        name: 'general_help',
+        state_prompt: 'Answer the caller question. If you cannot help, offer to transfer to a human.',
+        transitions: [
+          {
+            name: 'help_done',
+            description: 'Question answered',
+            destination: 'farewell',
+          },
+        ],
+      },
+      {
+        name: 'farewell',
+        state_prompt: 'Thank the caller and end the call politely. Use end_call tool.',
+        transitions: [],
+      },
+    ],
+    starting_state: 'greeting',
+  }),
+});
+
+const llmData = await llmResponse.json();
+const llmId = llmData.llm_id;
+
+// Now create the agent (connects voice + LLM)
+const agentResponse = await fetch('https://api.retellai.com/v2/create-agent', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
   },
-  firstMessage: "Hello! Thanks for calling. How can I help you today?",
-  endCallMessage: "Thank you for calling. Have a great day!",
-  transcriber: {
-    provider: "deepgram",
-    model: "nova-2",
-    language: "en"
+  body: JSON.stringify({
+    agent_name: 'Qualia Appointment Scheduler',
+    voice_id: '21m00Tcm4TlvDq8ikWAM',  // ElevenLabs Rachel
+    response_engine: {
+      type: 'retell-llm',
+      llm_id: llmId,
+    },
+    language: 'en-US',
+    voice_temperature: 1,
+    voice_speed: 1,
+    responsiveness: 1,
+    interruption_sensitivity: 1,
+    enable_backchannel: true,
+    backchannel_frequency: 0.8,
+    reminder_trigger_ms: 10000,
+    reminder_max_count: 2,
+    ambient_sound: null,
+    webhook_url: 'https://YOUR_PROJECT.supabase.co/functions/v1/retell-webhook',
+    post_call_analysis_data: [
+      {
+        type: 'enum',
+        name: 'call_outcome',
+        description: 'The outcome of the call',
+        options: ['appointment_booked', 'appointment_checked', 'general_inquiry', 'transferred', 'abandoned'],
+      },
+      {
+        type: 'string',
+        name: 'call_summary',
+        description: 'A brief 1-2 sentence summary of what happened on the call',
+      },
+      {
+        type: 'boolean',
+        name: 'caller_satisfied',
+        description: 'Whether the caller seemed satisfied with the interaction',
+      },
+    ],
+  }),
+});
+
+const agentData = await agentResponse.json();
+console.log('Agent created:', agentData.agent_id);
+```
+
+### Assign Phone Number
+
+```typescript
+// Purchase and assign a phone number
+const phoneResponse = await fetch('https://api.retellai.com/v2/create-phone-number', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
   },
-  serverUrl: "https://your-app.com/api/vapi-webhook"
-};
+  body: JSON.stringify({
+    agent_id: agentData.agent_id,
+    area_code: 357,  // Cyprus area code (adjust per project)
+  }),
+});
+
+const phoneData = await phoneResponse.json();
+console.log('Phone number assigned:', phoneData.phone_number);
+```
+
+### Import Existing Number (Telnyx/Twilio)
+
+```typescript
+// If bringing your own number via Telnyx
+const importResponse = await fetch('https://api.retellai.com/v2/import-phone-number', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    agent_id: agentData.agent_id,
+    phone_number: '+35712345678',
+    telephony_provider: 'telnyx',       // 'telnyx' | 'twilio' | 'vonage'
+    telephony_credentials: {
+      telnyx_api_key: Deno.env.get('TELNYX_API_KEY'),
+      telnyx_app_connection_id: Deno.env.get('TELNYX_CONNECTION_ID'),
+    },
+  }),
+});
+```
+
+### Update Agent (PATCH)
+
+```typescript
+// Update an existing agent
+await fetch(`https://api.retellai.com/v2/update-agent/${agentId}`, {
+  method: 'PATCH',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    voice_id: 'NEW_VOICE_ID',
+    webhook_url: 'https://YOUR_PROJECT.supabase.co/functions/v1/retell-webhook',
+  }),
+});
 ```
 
-### Create via VAPI
-> Use VAPI MCP tools (available via settings.json) or direct VAPI API via curl/WebFetch.
-> Example: `curl -X POST https://api.vapi.ai/assistant -H "Authorization: Bearer $VAPI_API_KEY" -d '<config>'`
+---
 
 ## Stage 3: Setup Supabase Backend
 
 ### Database Schema
+
 ```sql
--- Appointments table
+-- Migration: supabase/migrations/YYYYMMDD_voice_agent_tables.sql
+
+-- Call logs — every call tracked
+CREATE TABLE call_logs (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  call_id TEXT UNIQUE NOT NULL,            -- Retell call ID
+  agent_id TEXT NOT NULL,                  -- Retell agent ID
+  from_number TEXT,                        -- Caller phone
+  to_number TEXT,                          -- Agent phone
+  direction TEXT NOT NULL DEFAULT 'inbound'
+    CHECK (direction IN ('inbound', 'outbound', 'web')),
+  call_status TEXT NOT NULL DEFAULT 'started'
+    CHECK (call_status IN ('started', 'ended', 'error')),
+  disconnection_reason TEXT,               -- 'user_hangup', 'agent_hangup', 'call_transfer', 'error', etc.
+  duration_ms INTEGER,
+  transcript TEXT,
+  transcript_object JSONB,                 -- Full structured transcript
+  call_analysis JSONB,                     -- Post-call analysis results
+  recording_url TEXT,
+  metadata JSONB DEFAULT '{}',
+  started_at TIMESTAMPTZ DEFAULT NOW(),
+  ended_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Agent state — persistent context between calls per phone number
+CREATE TABLE agent_state (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  phone_number TEXT UNIQUE NOT NULL,
+  agent_id TEXT NOT NULL,
+  last_call_id TEXT REFERENCES call_logs(call_id),
+  context JSONB DEFAULT '{}',              -- Arbitrary state (name, preferences, history)
+  call_count INTEGER DEFAULT 0,
+  first_call_at TIMESTAMPTZ DEFAULT NOW(),
+  last_call_at TIMESTAMPTZ DEFAULT NOW(),
+  updated_at TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Appointments — example domain table
 CREATE TABLE appointments (
   id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  call_id TEXT REFERENCES call_logs(call_id),
   customer_phone TEXT NOT NULL,
   customer_name TEXT,
   service_type TEXT NOT NULL,
   appointment_date DATE NOT NULL,
   appointment_time TIME NOT NULL,
-  status TEXT DEFAULT 'scheduled' CHECK (status IN ('scheduled', 'confirmed', 'cancelled', 'completed')),
+  status TEXT DEFAULT 'scheduled'
+    CHECK (status IN ('scheduled', 'confirmed', 'cancelled', 'completed', 'no_show')),
   notes TEXT,
+  reminder_sent BOOLEAN DEFAULT FALSE,
   created_at TIMESTAMPTZ DEFAULT NOW(),
   updated_at TIMESTAMPTZ DEFAULT NOW()
 );
 
--- Call logs
-CREATE TABLE call_logs (
-  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
-  call_id TEXT UNIQUE NOT NULL,
-  phone_number TEXT NOT NULL,
-  duration_seconds INTEGER,
-  transcript TEXT,
-  outcome TEXT,
-  created_at TIMESTAMPTZ DEFAULT NOW()
-);
-
--- Agent state (for context between calls)
-CREATE TABLE agent_state (
-  phone_number TEXT PRIMARY KEY,
-  last_call_id TEXT,
-  context JSONB DEFAULT '{}',
-  updated_at TIMESTAMPTZ DEFAULT NOW()
-);
+-- Indexes
+CREATE INDEX idx_call_logs_call_id ON call_logs(call_id);
+CREATE INDEX idx_call_logs_from_number ON call_logs(from_number);
+CREATE INDEX idx_call_logs_started_at ON call_logs(started_at DESC);
+CREATE INDEX idx_agent_state_phone ON agent_state(phone_number);
+CREATE INDEX idx_appointments_date ON appointments(appointment_date);
+CREATE INDEX idx_appointments_phone ON appointments(customer_phone);
 
--- Enable RLS
-ALTER TABLE appointments ENABLE ROW LEVEL SECURITY;
+-- Enable RLS on all tables
 ALTER TABLE call_logs ENABLE ROW LEVEL SECURITY;
 ALTER TABLE agent_state ENABLE ROW LEVEL SECURITY;
+ALTER TABLE appointments ENABLE ROW LEVEL SECURITY;
 
--- RLS Policies: service role only (called from edge functions)
-CREATE POLICY "Service role full access" ON appointments
-  FOR ALL USING (auth.role() = 'service_role');
-
+-- RLS Policies: service_role only (Edge Functions use service_role key)
+-- These tables are written to by webhooks, not by end users directly.
 CREATE POLICY "Service role full access" ON call_logs
   FOR ALL USING (auth.role() = 'service_role');
 
 CREATE POLICY "Service role full access" ON agent_state
   FOR ALL USING (auth.role() = 'service_role');
+
+CREATE POLICY "Service role full access" ON appointments
+  FOR ALL USING (auth.role() = 'service_role');
+
+-- If you also need an admin dashboard with authenticated users:
+-- CREATE POLICY "Admins can read call logs" ON call_logs
+--   FOR SELECT USING (
+--     EXISTS (
+--       SELECT 1 FROM profiles
+--       WHERE profiles.id = auth.uid()
+--       AND profiles.role = 'admin'
+--     )
+--   );
+
+-- Updated_at trigger
+CREATE OR REPLACE FUNCTION update_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = NOW();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+CREATE TRIGGER tr_appointments_updated
+  BEFORE UPDATE ON appointments
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
+
+CREATE TRIGGER tr_agent_state_updated
+  BEFORE UPDATE ON agent_state
+  FOR EACH ROW EXECUTE FUNCTION update_updated_at();
 ```
 
-### API Functions
+---
+
+## Stage 4: Configure Webhooks
+
+### Retell Webhook Events
+
+Retell sends POST requests to your `webhook_url` with these event types:
+
+| Event | When | Key Data |
+|-------|------|----------|
+| `call_started` | Call begins | call_id, from_number, to_number, agent_id |
+| `call_ended` | Call finishes | call_id, duration_ms, transcript, recording_url, disconnection_reason |
+| `call_analyzed` | Post-call analysis complete | call_id, call_analysis (custom fields you defined) |
+| `tool_call_invoked` | Agent calls a custom tool | tool_call_id, name, arguments |
+| `tool_call_result` | Tool execution completed | tool_call_id, result |
+
+### Webhook Signature Verification
+
+Retell signs webhooks using `x-retell-signature` header with HMAC-SHA256.
+
 ```typescript
-// supabase/functions/book-appointment/index.ts
-import { z } from "https://deno.land/x/zod/mod.ts"
+import { createHmac } from "node:crypto";
 
-const BookingSchema = z.object({
-  phone: z.string().min(10),
-  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-  time: z.string().regex(/^\d{2}:\d{2}$/),
-  service: z.string().min(1),
-})
+function verifyRetellSignature(
+  body: string,
+  signature: string | null,
+  apiKey: string
+): boolean {
+  if (!signature) return false;
+
+  const hmac = createHmac('sha256', apiKey);
+  hmac.update(body);
+  const expectedSignature = hmac.digest('base64');
+
+  return signature === expectedSignature;
+}
+```
+
+> **Important:** Retell uses the API key itself as the HMAC secret for webhook verification. Not a separate webhook secret.
+
+### Webhook Handler (Supabase Edge Function)
+
+```typescript
+// supabase/functions/retell-webhook/index.ts
+import { serve } from "https://deno.land/std@0.208.0/http/server.ts";
+import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
+import { createHmac } from "node:crypto";
+import { z } from "https://deno.land/x/zod@v3.22.4/mod.ts";
+
+// --- Signature Verification ---
+function verifyRetellSignature(body: string, signature: string | null): boolean {
+  if (!signature) return false;
+  const apiKey = Deno.env.get('RETELL_API_KEY')!;
+  const hmac = createHmac('sha256', apiKey);
+  hmac.update(body);
+  const expected = hmac.digest('base64');
+  return signature === expected;
+}
 
-serve(async (req) => {
+// --- Zod Schemas ---
+const CallStartedSchema = z.object({
+  event: z.literal('call_started'),
+  call: z.object({
+    call_id: z.string(),
+    agent_id: z.string(),
+    from_number: z.string().optional(),
+    to_number: z.string().optional(),
+    direction: z.enum(['inbound', 'outbound', 'web']),
+    metadata: z.record(z.unknown()).optional(),
+  }),
+});
+
+const CallEndedSchema = z.object({
+  event: z.literal('call_ended'),
+  call: z.object({
+    call_id: z.string(),
+    agent_id: z.string(),
+    from_number: z.string().optional(),
+    to_number: z.string().optional(),
+    direction: z.enum(['inbound', 'outbound', 'web']),
+    duration_ms: z.number().optional(),
+    transcript: z.string().optional(),
+    transcript_object: z.array(z.unknown()).optional(),
+    recording_url: z.string().optional(),
+    disconnection_reason: z.string().optional(),
+    metadata: z.record(z.unknown()).optional(),
+  }),
+});
+
+const CallAnalyzedSchema = z.object({
+  event: z.literal('call_analyzed'),
+  call: z.object({
+    call_id: z.string(),
+    call_analysis: z.record(z.unknown()).optional(),
+  }),
+});
+
+// --- Main Handler ---
+serve(async (req: Request) => {
+  // Only accept POST
+  if (req.method !== 'POST') {
+    return new Response('Method not allowed', { status: 405 });
+  }
+
+  const body = await req.text();
+
+  // 1. Verify webhook signature
+  const signature = req.headers.get('x-retell-signature');
+  if (!verifyRetellSignature(body, signature)) {
+    console.error('Invalid webhook signature');
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // 2. Parse body
+  let payload: unknown;
   try {
-  const raw = await req.json();
-  const { phone, date, time, service } = BookingSchema.parse(raw);
+    payload = JSON.parse(body);
+  } catch {
+    return new Response('Invalid JSON', { status: 400 });
+  }
 
+  // 3. Initialize Supabase client (service role for DB writes)
   const supabase = createClient(
     Deno.env.get('SUPABASE_URL')!,
     Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
   );
 
-  // Check availability
-  const { data: existing } = await supabase
-    .from('appointments')
-    .select('id')
-    .eq('appointment_date', date)
-    .eq('appointment_time', time)
-    .single();
-
-  if (existing) {
-    return new Response(JSON.stringify({
-      success: false,
-      message: "That time slot is already booked."
-    }));
-  }
+  // 4. Route by event type
+  const event = (payload as { event?: string }).event;
+
+  try {
+    switch (event) {
+      case 'call_started': {
+        const parsed = CallStartedSchema.parse(payload);
+        const { call } = parsed;
+
+        // Insert initial call log
+        await supabase.from('call_logs').insert({
+          call_id: call.call_id,
+          agent_id: call.agent_id,
+          from_number: call.from_number ?? null,
+          to_number: call.to_number ?? null,
+          direction: call.direction,
+          call_status: 'started',
+          metadata: call.metadata ?? {},
+        });
+
+        // Update agent state (track returning callers)
+        if (call.from_number) {
+          await supabase.from('agent_state').upsert(
+            {
+              phone_number: call.from_number,
+              agent_id: call.agent_id,
+              last_call_id: call.call_id,
+              last_call_at: new Date().toISOString(),
+              call_count: 1, // Will be incremented via raw SQL below
+            },
+            { onConflict: 'phone_number' }
+          );
+
+          // Increment call count for returning callers
+          await supabase.rpc('increment_call_count', {
+            p_phone: call.from_number,
+          });
+        }
+
+        console.log(`Call started: ${call.call_id}`);
+        break;
+      }
+
+      case 'call_ended': {
+        const parsed = CallEndedSchema.parse(payload);
+        const { call } = parsed;
+
+        // Update call log with final data
+        await supabase
+          .from('call_logs')
+          .update({
+            call_status: 'ended',
+            duration_ms: call.duration_ms ?? null,
+            transcript: call.transcript ?? null,
+            transcript_object: call.transcript_object ?? null,
+            recording_url: call.recording_url ?? null,
+            disconnection_reason: call.disconnection_reason ?? null,
+            ended_at: new Date().toISOString(),
+          })
+          .eq('call_id', call.call_id);
+
+        console.log(`Call ended: ${call.call_id} (${call.duration_ms}ms)`);
+        break;
+      }
 
-  // Book appointment
-  const { data, error } = await supabase
-    .from('appointments')
-    .insert({
-      customer_phone: phone,
-      appointment_date: date,
-      appointment_time: time,
-      service_type: service
-    })
-    .select()
-    .single();
-
-  return new Response(JSON.stringify({
-    success: true,
-    appointment: data,
-    message: `Appointment booked for ${date} at ${time}`
-  }));
+      case 'call_analyzed': {
+        const parsed = CallAnalyzedSchema.parse(payload);
+        const { call } = parsed;
+
+        // Store post-call analysis
+        await supabase
+          .from('call_logs')
+          .update({
+            call_analysis: call.call_analysis ?? null,
+          })
+          .eq('call_id', call.call_id);
+
+        console.log(`Call analyzed: ${call.call_id}`);
+        break;
+      }
+
+      default:
+        console.log(`Unhandled event type: ${event}`);
+    }
   } catch (error) {
-    console.error("Booking error:", error);
-    return new Response(JSON.stringify({
-      success: false,
-      message: "Failed to process booking request"
-    }), { status: 500 });
+    console.error(`Error processing ${event}:`, error);
+    // Return 200 anyway to prevent Retell from retrying on validation errors.
+    // Log the error for debugging. Only return 5xx for transient failures.
   }
+
+  return new Response(JSON.stringify({ received: true }), {
+    status: 200,
+    headers: { 'Content-Type': 'application/json' },
+  });
 });
 ```
 
-## Stage 4: Configure Webhooks
+### Helper RPC for Call Count Increment
+
+```sql
+-- Migration: supabase/migrations/YYYYMMDD_increment_call_count.sql
+CREATE OR REPLACE FUNCTION increment_call_count(p_phone TEXT)
+RETURNS VOID AS $$
+BEGIN
+  UPDATE agent_state
+  SET call_count = call_count + 1
+  WHERE phone_number = p_phone;
+END;
+$$ LANGUAGE plpgsql SECURITY DEFINER;
+```
+
+### Tool Handler (Supabase Edge Function)
+
+Retell calls your custom tool URLs directly. Each tool gets its own handler or a unified one:
 
-### VAPI Webhook Handler
 ```typescript
-// supabase/functions/vapi-webhook/index.ts
-serve(async (req) => {
-  try {
-  // Verify VAPI webhook signature
-  const signature = req.headers.get('x-vapi-signature');
-  const body = await req.text();
+// supabase/functions/retell-tool-handler/index.ts
+import { serve } from "https://deno.land/std@0.208.0/http/server.ts";
+import { createClient } from "https://esm.sh/@supabase/supabase-js@2";
+import { z } from "https://deno.land/x/zod@v3.22.4/mod.ts";
 
-  if (!verifyVapiSignature(body, signature, Deno.env.get('VAPI_WEBHOOK_SECRET')!)) {
-    return new Response('Unauthorized', { status: 401 });
+// --- Zod Schemas for Tool Arguments ---
+const BookAppointmentArgs = z.object({
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be YYYY-MM-DD'),
+  time: z.string().regex(/^\d{2}:\d{2}$/, 'Time must be HH:MM'),
+  service: z.string().min(1),
+  caller_name: z.string().min(1),
+});
+
+const CheckAvailabilityArgs = z.object({
+  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+});
+
+// --- Main Handler ---
+serve(async (req: Request) => {
+  if (req.method !== 'POST') {
+    return new Response('Method not allowed', { status: 405 });
   }
 
-  const event = JSON.parse(body);
-  const supabase = createClient(/* ... */);
+  const body = await req.json();
+
+  // Retell sends: { tool_call_id, name, arguments, call }
+  const { name, arguments: args, call } = body;
+
+  const supabase = createClient(
+    Deno.env.get('SUPABASE_URL')!,
+    Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!
+  );
+
+  try {
+    switch (name) {
+      case 'book_appointment': {
+        const parsed = BookAppointmentArgs.parse(args);
+
+        // Check if slot is taken
+        const { data: existing } = await supabase
+          .from('appointments')
+          .select('id')
+          .eq('appointment_date', parsed.date)
+          .eq('appointment_time', parsed.time)
+          .neq('status', 'cancelled')
+          .maybeSingle();
 
-  switch (event.message.type) {
-    case 'function-call':
-      // Handle tool calls
-      const { name, parameters } = event.message.functionCall;
+        if (existing) {
+          return Response.json({
+            result: `Sorry, that time slot on ${parsed.date} at ${parsed.time} is already booked. Please choose another time.`,
+          });
+        }
 
-      switch (name) {
-        case 'book_appointment':
-          const result = await bookAppointment(parameters);
-          return new Response(JSON.stringify({ result }));
+        // Book the appointment
+        const { data: appointment, error } = await supabase
+          .from('appointments')
+          .insert({
+            call_id: call?.call_id ?? null,
+            customer_phone: call?.from_number ?? 'unknown',
+            customer_name: parsed.caller_name,
+            service_type: parsed.service,
+            appointment_date: parsed.date,
+            appointment_time: parsed.time,
+          })
+          .select()
+          .single();
 
-        case 'check_availability':
-          const slots = await checkAvailability(parameters);
-          return new Response(JSON.stringify({ result: slots }));
+        if (error) throw error;
 
-        case 'get_customer_appointments':
-          const appointments = await getAppointments(parameters.phone);
-          return new Response(JSON.stringify({ result: appointments }));
+        return Response.json({
+          result: `Appointment booked successfully for ${parsed.caller_name} on ${parsed.date} at ${parsed.time} for ${parsed.service}. Appointment ID: ${appointment.id}.`,
+        });
       }
-      break;
-
-    case 'end-of-call-report':
-      // Log call
-      await supabase.from('call_logs').insert({
-        call_id: event.call.id,
-        phone_number: event.call.customer.number,
-        duration_seconds: event.call.duration,
-        transcript: event.transcript,
-        outcome: event.call.endedReason
-      });
-      break;
 
-    case 'status-update':
-      console.log('Call status:', event.status);
-      break;
-  }
+      case 'check_availability': {
+        const parsed = CheckAvailabilityArgs.parse(args);
 
-  return new Response('OK');
-  } catch (error) {
-    console.error("Webhook error:", error);
-    return new Response(JSON.stringify({ error: "Internal server error" }), {
-      status: 500,
-      headers: { "Content-Type": "application/json" },
-    });
-  }
-});
-```
+        // Get booked slots for that date
+        const { data: booked } = await supabase
+          .from('appointments')
+          .select('appointment_time')
+          .eq('appointment_date', parsed.date)
+          .neq('status', 'cancelled');
 
-### Tool Definitions
-```typescript
-const tools = [
-  {
-    type: "function",
-    function: {
-      name: "book_appointment",
-      description: "Book a new appointment for the caller",
-      parameters: {
-        type: "object",
-        properties: {
-          date: { type: "string", description: "Date in YYYY-MM-DD format" },
-          time: { type: "string", description: "Time in HH:MM format" },
-          service: { type: "string", description: "Type of service" }
-        },
-        required: ["date", "time", "service"]
+        const bookedTimes = new Set((booked ?? []).map(b => b.appointment_time));
+
+        // Generate available slots (9 AM to 5 PM, 30-min intervals)
+        const allSlots = [];
+        for (let h = 9; h < 17; h++) {
+          for (const m of ['00', '30']) {
+            const slot = `${h.toString().padStart(2, '0')}:${m}`;
+            if (!bookedTimes.has(slot)) {
+              allSlots.push(slot);
+            }
+          }
+        }
+
+        if (allSlots.length === 0) {
+          return Response.json({
+            result: `No available slots on ${parsed.date}. Please try another date.`,
+          });
+        }
+
+        return Response.json({
+          result: `Available times on ${parsed.date}: ${allSlots.join(', ')}`,
+        });
       }
+
+      default:
+        return Response.json({
+          result: `Unknown tool: ${name}`,
+        });
     }
-  },
-  {
-    type: "function",
-    function: {
-      name: "check_availability",
-      description: "Check available appointment slots",
-      parameters: {
-        type: "object",
-        properties: {
-          date: { type: "string", description: "Date to check" }
-        },
-        required: ["date"]
-      }
+  } catch (error) {
+    console.error(`Tool ${name} error:`, error);
+
+    if (error instanceof z.ZodError) {
+      return Response.json({
+        result: 'I need a bit more information. Could you provide the date and time again?',
+      });
     }
+
+    return Response.json({
+      result: 'Sorry, I encountered an error processing your request. Let me try again.',
+    });
   }
-];
+});
 ```
 
+> **Key pattern:** Tool handlers return `{ result: "..." }`. The `result` string is what the agent speaks back to the caller. Write it as natural speech, not JSON data.
+
+---
+
 ## Stage 5: Deploy & Test
 
 ### Deploy Steps
+
 ```bash
-# Deploy Supabase functions
-supabase functions deploy book-appointment
-supabase functions deploy vapi-webhook
+# 1. Apply database migration
+supabase db push
+
+# 2. Set secrets for Edge Functions
+supabase secrets set RETELL_API_KEY=key_...
+supabase secrets set ELEVENLABS_API_KEY=xi_...
+
+# 3. Deploy Edge Functions
+supabase functions deploy retell-webhook --no-verify-jwt
+supabase functions deploy retell-tool-handler --no-verify-jwt
+
+# 4. Get the function URLs
+# https://YOUR_PROJECT.supabase.co/functions/v1/retell-webhook
+# https://YOUR_PROJECT.supabase.co/functions/v1/retell-tool-handler
 
-# Update VAPI assistant with webhook URL
-# Use VAPI dashboard or API
+# 5. Update Retell agent with webhook URL (via API or dashboard)
+curl -X PATCH "https://api.retellai.com/v2/update-agent/YOUR_AGENT_ID" \
+  -H "Authorization: Bearer $RETELL_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"webhook_url": "https://YOUR_PROJECT.supabase.co/functions/v1/retell-webhook"}'
 
-# Test with a call
-vapi call --assistant-id your-assistant-id --to +1234567890
+# 6. Test with a web call (no phone needed)
+curl -X POST "https://api.retellai.com/v2/create-web-call" \
+  -H "Authorization: Bearer $RETELL_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"agent_id": "YOUR_AGENT_ID"}'
+# Returns: { "call_id": "...", "access_token": "..." }
+# Use access_token with Retell Web SDK to test in browser
+
+# 7. Test with a phone call
+curl -X POST "https://api.retellai.com/v2/create-phone-call" \
+  -H "Authorization: Bearer $RETELL_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "from_number": "+1234567890",
+    "to_number": "+0987654321",
+    "agent_id": "YOUR_AGENT_ID"
+  }'
 ```
 
+> **Important:** Use `--no-verify-jwt` for webhook and tool handler functions. Retell authenticates via `x-retell-signature`, not JWT. The functions verify signatures themselves.
+
 ### Test Scenarios
-1. **Happy path**: Book appointment successfully
-2. **Conflict**: Time slot unavailable
-3. **Edge case**: Invalid date format
-4. **Error handling**: Database connection fails
-5. **Context persistence**: Caller calls back
+
+| # | Scenario | Expected Outcome |
+|---|----------|------------------|
+| 1 | Happy path: book appointment | Agent collects info, calls book_appointment tool, confirms booking |
+| 2 | Slot conflict | Agent reports slot unavailable, suggests alternatives |
+| 3 | Invalid date from caller | Agent asks caller to repeat/clarify the date |
+| 4 | Caller interrupts mid-sentence | Agent stops speaking and listens |
+| 5 | Caller asks for human | Agent transfers (or apologizes if no transfer configured) |
+| 6 | Returning caller | agent_state context loaded, call_count incremented |
+| 7 | Webhook failure | Returns 200 anyway, error logged for debugging |
+| 8 | Silence timeout | Agent nudges after reminder_trigger_ms, ends after max nudges |
+
+### Verify Webhook Delivery
+
+```bash
+# Check Retell webhook logs via API
+curl "https://api.retellai.com/v2/list-calls?agent_id=YOUR_AGENT_ID&limit=5" \
+  -H "Authorization: Bearer $RETELL_API_KEY" | jq '.[]|{call_id,call_status,disconnection_reason,duration_ms}'
+
+# Check Supabase Edge Function logs
+supabase functions logs retell-webhook --limit 20
+
+# Verify data landed in DB
+supabase db execute "SELECT call_id, call_status, duration_ms, ended_at FROM call_logs ORDER BY created_at DESC LIMIT 5"
+```
+
+---
 
 ## Voice Selection (ElevenLabs)
 
-| Use Case | Voice | Why |
-|----------|-------|-----|
-| Professional | Rachel | Calm, clear, authoritative |
-| Friendly | Bella | Warm, approachable |
-| Energetic | Elli | Upbeat, engaging |
-| Corporate | Adam | Professional male |
+### Pre-built Voices
+
+| Use Case | Voice Name | Voice ID | Style | Best For |
+|----------|-----------|----------|-------|----------|
+| Professional Female | Rachel | `21m00Tcm4TlvDq8ikWAM` | Calm, clear, authoritative | Medical, legal, enterprise |
+| Friendly Female | Bella | `EXAVITQu4vr4xnSDxMaL` | Warm, approachable, casual | Retail, hospitality, support |
+| Energetic Female | Elli | `MF3mGyEYCl7XYWbV9V6O` | Upbeat, enthusiastic | Sales, marketing, events |
+| Professional Male | Adam | `pNInz6obpgDQGcFmaJgB` | Deep, confident, steady | Finance, corporate, B2B |
+| Conversational Male | Antoni | `ErXwobaYiN019PkySvjV` | Natural, relaxed | General-purpose, support |
+| Warm Male | Josh | `TxGEqnHWrfWFTfGW9XjX` | Friendly, trustworthy | Healthcare, insurance |
+| Authoritative Male | Arnold | `VR6AewLTigWG4xSOukaG` | Strong, commanding | Emergency, security |
+| Young Female | Dorothy | `ThT5KcBeYPX3keUQqHPh` | Bright, clear | Startups, tech support |
+
+### Multilingual Voices
+
+| Language | Voice Name | Voice ID | Notes |
+|----------|-----------|----------|-------|
+| Arabic | Custom clone | (clone your own) | Best results with voice cloning |
+| Greek | Custom clone | (clone your own) | Limited pre-built options |
+| Multilingual | Eleven Multilingual v2 | Any v2 voice | All v2 voices support 29 languages |
+
+> **Tip:** All ElevenLabs voices with "v2" or "Multilingual v2" model support automatic language detection across 29 languages. Use these for multilingual agents.
+
+### Voice Cloning (Custom Brand Voice)
+
+```typescript
+// Clone a voice from audio samples
+const formData = new FormData();
+formData.append('name', 'Brand Voice');
+formData.append('description', 'Company brand voice for phone agents');
+formData.append('files', audioFile1);  // Min 1 sample, recommend 3+ minutes total
+formData.append('files', audioFile2);
+formData.append('labels', JSON.stringify({ accent: 'neutral', gender: 'female' }));
+
+const response = await fetch('https://api.elevenlabs.io/v1/voices/add', {
+  method: 'POST',
+  headers: {
+    'xi-api-key': ELEVENLABS_API_KEY,
+  },
+  body: formData,
+});
+
+const voice = await response.json();
+console.log('Cloned voice ID:', voice.voice_id);
+// Use this voice_id when creating the Retell agent
+```
+
+### List Available Voices
+
+```typescript
+// Fetch all available voices from ElevenLabs
+const response = await fetch('https://api.elevenlabs.io/v1/voices', {
+  headers: { 'xi-api-key': ELEVENLABS_API_KEY },
+});
+const { voices } = await response.json();
+
+voices.forEach((v: { name: string; voice_id: string; labels: Record<string, string> }) => {
+  console.log(`${v.name} (${v.voice_id}) — ${v.labels?.accent ?? 'unknown accent'}, ${v.labels?.gender ?? ''}`);
+});
+```
+
+---
+
+## Advanced Patterns
+
+### Outbound Calling (Proactive Calls)
+
+```typescript
+// Trigger an outbound call (e.g., appointment reminders)
+async function makeOutboundCall(
+  agentId: string,
+  fromNumber: string,
+  toNumber: string,
+  metadata?: Record<string, string>
+) {
+  const response = await fetch('https://api.retellai.com/v2/create-phone-call', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${RETELL_API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      agent_id: agentId,
+      from_number: fromNumber,
+      to_number: toNumber,
+      metadata: metadata ?? {},
+      retell_llm_dynamic_variables: {
+        // Inject variables into the LLM prompt at call time
+        customer_name: 'John',
+        appointment_date: '2026-04-05',
+        appointment_time: '14:00',
+      },
+    }),
+  });
+
+  return response.json();
+}
+
+// Example: reminder cron job (Supabase Edge Function + pg_cron)
+// Run daily at 8 AM, call patients with appointments tomorrow
+```
+
+### Dynamic Variables (Personalization)
+
+Retell supports `retell_llm_dynamic_variables` to inject context into the LLM prompt at call time:
+
+```typescript
+// In your LLM prompt, use {{variable_name}} syntax:
+// "Hello {{customer_name}}, I'm calling about your appointment on {{appointment_date}}."
+
+// When creating the call, pass the variables:
+const call = await fetch('https://api.retellai.com/v2/create-phone-call', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    agent_id: agentId,
+    from_number: fromNumber,
+    to_number: toNumber,
+    retell_llm_dynamic_variables: {
+      customer_name: 'Sarah',
+      appointment_date: 'April 5th',
+      company_name: 'Qualia Solutions',
+    },
+  }),
+});
+```
+
+### Call Transfer
+
+```typescript
+// In your Retell LLM config, add a transfer tool:
+{
+  type: 'transfer_call',
+  name: 'transfer_to_human',
+  description: 'Transfer the caller to a human agent when they request one or when you cannot help',
+  number: '+35799999999',  // Human agent / call center number
+}
+```
+
+### Web Call (Browser-Based)
+
+```typescript
+// Create a web call for browser-based voice agents
+const webCall = await fetch('https://api.retellai.com/v2/create-web-call', {
+  method: 'POST',
+  headers: {
+    'Authorization': `Bearer ${RETELL_API_KEY}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    agent_id: agentId,
+    metadata: { source: 'website', page: '/contact' },
+    retell_llm_dynamic_variables: {
+      customer_name: 'Website Visitor',
+    },
+  }),
+});
+
+const { access_token } = await webCall.json();
+// Pass access_token to Retell Web SDK on the frontend
+```
+
+### Frontend Web SDK Integration
+
+```typescript
+// npm install retell-client-js-sdk
+import { RetellWebClient } from 'retell-client-js-sdk';
+
+const retellClient = new RetellWebClient();
+
+// Start call with access token from your backend
+await retellClient.startCall({
+  accessToken: accessToken,  // From create-web-call response
+  sampleRate: 24000,
+  emitRawAudioSamples: false,
+});
+
+// Event handlers
+retellClient.on('call_started', () => {
+  console.log('Call connected');
+});
+
+retellClient.on('call_ended', () => {
+  console.log('Call ended');
+});
+
+retellClient.on('agent_start_talking', () => {
+  // Update UI — agent is speaking
+});
+
+retellClient.on('agent_stop_talking', () => {
+  // Update UI — agent stopped
+});
+
+retellClient.on('error', (error) => {
+  console.error('Retell error:', error);
+  retellClient.stopCall();
+});
+
+// End call
+retellClient.stopCall();
+```
+
+---
 
 ## Best Practices
 
-1. **Keep responses short** - 1-2 sentences max
-2. **Confirm important info** - Repeat back dates/times
-3. **Handle interruptions** - Allow user to interrupt
-4. **Provide escape routes** - "Say 'operator' for help"
-5. **Log everything** - For debugging and improvement
-6. **Test extensively** - Real phone calls, various accents
+1. **Keep responses short** — 1-2 sentences max. Long agent monologues make callers hang up.
+2. **Confirm critical info** — Always repeat dates, times, and names back before acting.
+3. **Handle interruptions** — Set `interruption_sensitivity` to 1 for natural conversation.
+4. **Use backchannels** — Enable `enable_backchannel` for natural "uh huh" filler while listening.
+5. **Tool results are speech** — Return natural language in `result`, not JSON. The agent speaks it.
+6. **Validate on the tool side** — Use Zod in tool handlers. Return friendly error messages, not stack traces.
+7. **Log everything** — Store full transcripts and call analysis for debugging and improvement.
+8. **Test with real calls** — Browser testing is fast, but always test real phone calls before going live.
+9. **Use post-call analysis** — Define `post_call_analysis_data` to auto-extract outcomes, sentiment, etc.
+10. **Signature verification is mandatory** — Never skip `x-retell-signature` verification on webhooks.
+11. **Ambient sound** — Use `coffee-shop` or `call-center` ambient sound for more natural feel.
+12. **Dynamic variables** — Use `retell_llm_dynamic_variables` for personalization on outbound calls.
+
+## Retell API Quick Reference
+
+| Action | Method | Endpoint |
+|--------|--------|----------|
+| Create LLM | POST | `https://api.retellai.com/v2/create-retell-llm` |
+| Create Agent | POST | `https://api.retellai.com/v2/create-agent` |
+| Update Agent | PATCH | `https://api.retellai.com/v2/update-agent/{agent_id}` |
+| Get Agent | GET | `https://api.retellai.com/v2/get-agent/{agent_id}` |
+| List Agents | GET | `https://api.retellai.com/v2/list-agents` |
+| Delete Agent | DELETE | `https://api.retellai.com/v2/delete-agent/{agent_id}` |
+| Create Phone Number | POST | `https://api.retellai.com/v2/create-phone-number` |
+| Import Phone Number | POST | `https://api.retellai.com/v2/import-phone-number` |
+| Create Phone Call | POST | `https://api.retellai.com/v2/create-phone-call` |
+| Create Web Call | POST | `https://api.retellai.com/v2/create-web-call` |
+| List Calls | GET | `https://api.retellai.com/v2/list-calls` |
+| Get Call | GET | `https://api.retellai.com/v2/get-call/{call_id}` |
+| Update Retell LLM | PATCH | `https://api.retellai.com/v2/update-retell-llm/{llm_id}` |
+
+All endpoints require header: `Authorization: Bearer {RETELL_API_KEY}`
 
 ## Integration with Other Skills
 
-- **voice-agent** - This skill (VAPI patterns, conversation flow, webhooks)
-- **supabase** - For database operations
-- **docs-lookup** - For VAPI/ElevenLabs/Deepgram API docs
+- **supabase** — Database operations, Edge Functions, migrations
+- **docs-lookup** — Retell AI / ElevenLabs API documentation
+- **deploy** — Production deployment pipeline
+- **ship** — Full deploy with quality gates
+
+## Key Decisions to Ask User
+
+- **Use case**: What should the agent do? (booking, support, sales, etc.)
+- **Voice gender/style**: Professional, friendly, energetic? (see Voice Selection table)
+- **Language**: English only or multilingual? (affects voice model selection)
+- **Custom voice**: Need voice cloning for brand consistency?
+- **Phone vs web**: Inbound phone calls, outbound calls, or browser widget?
+- **LLM**: Retell built-in (Claude/GPT) or custom LLM via OpenRouter?
+- **Transfer**: Should the agent be able to transfer to a human?
+- **Telephony**: Buy new number from Retell, or import existing (Telnyx/Twilio)?
 
 ## Trigger Phrases
 
@@ -405,3 +1301,12 @@ vapi call --assistant-id your-assistant-id --to +1234567890
 - "create voice assistant"
 - "voice AI for"
 - "phone bot for"
+- "retell agent"
+- "retell"
+- "elevenlabs"
+- "voice webhook"
+- "call agent"
+- "phone agent"
+- "voice automation"
+- "outbound calls"
+- "web call widget"