elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/08-VOICE-CALLS.md

@@ -0,0 +1,470 @@
+# Voice Calls
+
+> Inbound call handling, outbound call initiation, and post-call processing pipeline.
+> Last updated: 2026-04-02
+
+---
+
+## 1. Inbound Calls
+
+Inbound calls are received via ElevenLabs SIP trunk. Each phone number has an associated AI agent that answers the call. A schedule system automatically assigns and unassigns agents based on configured working hours.
+
+### 1.1 Phone Number Configuration
+
+Inbound call phone numbers are stored in the unified `phone_numbers` table with `phone_purpose = 'inbound_call'` and `phone_provider = 'elevenlabs'`.
+
+```
+phone_numbers (where phone_purpose = 'inbound_call')
+  phone_id                     UUID PK
+  phone_tenant_id              UUID FK -> tenants
+  phone_clinic_id              UUID? FK -> clinics
+  phone_number                 String            -- E.164 format
+  phone_purpose                'inbound_call'
+  phone_provider               'elevenlabs'
+  phone_elevenlabs_phone_id    String?           -- ElevenLabs phone number ID
+  phone_elevenlabs_agent_id    String?           -- ElevenLabs agent ID (external)
+  phone_agent_id               UUID? FK -> agents  -- Internal agent reference
+  phone_schedule_enabled       Boolean default false
+  phone_schedule               JSONB default []  -- [{day, start, end}]
+  phone_agent_assigned         Boolean default false  -- Current assignment state
+  phone_is_active              Boolean default true
+```
+
+**Key fields:**
+- `phone_elevenlabs_phone_id` -- the phone number resource ID on ElevenLabs. Required for API calls to assign/unassign agents.
+- `phone_elevenlabs_agent_id` -- the ElevenLabs agent ID that should answer calls on this number.
+- `phone_schedule` -- JSON array defining when the agent should be active, e.g. `[{day: 1, start: "09:00", end: "18:00"}, ...]`.
+- `phone_agent_assigned` -- tracks whether the agent is currently assigned on ElevenLabs. This is the actual state, not the desired state.
+
+### 1.2 Schedule-Based Agent Assignment
+
+A BullMQ repeatable job runs every 15 minutes to synchronize agent assignments with configured schedules.
+
+**Queue:** `inbound-call:schedule-sync`, repeatable every 15 minutes, concurrency 1.
+
+**Algorithm:**
+
+```
+For each phone_number where phone_purpose = 'inbound_call'
+  AND phone_schedule_enabled = true
+  AND phone_is_active = true:
+
+  1. Determine current time in clinic timezone
+  2. Find today's schedule entry in phone_schedule (match by day-of-week)
+  3. Check if current time falls within start..end window
+
+  If SHOULD BE ACTIVE and agent_assigned = false:
+    Call ElevenLabs API: PATCH /phone-numbers/{phoneId}
+      body: { agent_id: phone_elevenlabs_agent_id }
+    Set phone_agent_assigned = true
+
+  If SHOULD BE INACTIVE and agent_assigned = true:
+    Call ElevenLabs API: PATCH /phone-numbers/{phoneId}
+      body: { agent_id: null }
+    Set phone_agent_assigned = false
+```
+
+**Manual override:** The `POST /phone-numbers/:id/toggle-agent` endpoint allows admins to manually assign or unassign the agent regardless of schedule. The schedule sync will re-evaluate on its next run.
+
+### 1.3 Call Flow
+
+```
+Caller dials clinic number
+  |
+  v
+ElevenLabs SIP trunk receives call
+  |  Agent is assigned to this phone number
+  v
+ElevenLabs AI agent answers
+  |  Dynamic variables available: caller number
+  |  AI conducts conversation
+  |  May use tools: check_availability, reserve_slot, etc.
+  v
+Call ends
+  |
+  v
+ElevenLabs fires POST /webhooks/elevenlabs (post-call webhook)
+  |
+  v
+Post-call processing pipeline (Section 3)
+```
+
+---
+
+## 2. Outbound Calls
+
+### 2.1 AI-Initiated (`call_patient` Tool)
+
+During a WhatsApp conversation, the AI agent can decide to call the patient directly. This is exposed as the `call_patient` client tool.
+
+**Parameters:** `{reason?}` -- optional free-text reason for the call.
+
+**Flow:**
+
+```
+AI determines a call is needed
+  |
+  v
+AI calls tool: call_patient({reason: "Patient needs verbal confirmation"})
+  |
+  v
+CalendarTools handler:
+  1. Look up tenant's outbound phone number (phone_purpose = 'outbound_call')
+  2. Look up the agent configured for outbound calls
+  3. Build dynamic variables:
+     - patient_name: from ToolContext
+     - patient_phone: from ToolContext
+     - conversation_history: recent WhatsApp messages for context
+     - call_reason: from params
+  4. Call elevenlabsService.sipTrunkOutboundCall({
+       agentId,
+       fromPhoneNumber,
+       toPhoneNumber: ctx.patientPhone,
+       dynamicVariables
+     })
+  v
+ElevenLabs places outbound call via SIP trunk
+  |
+  v
+AI agent speaks with patient
+  |  Has full context from WhatsApp conversation
+  |  Can use all available tools
+  v
+Call ends --> post-call webhook --> processing pipeline
+```
+
+**Channel restriction:** The `call_patient` tool is only available on the `whatsapp` channel (it would not make sense to initiate a call from within a call).
+
+### 2.2 Batch Outbound Calls
+
+Batch outbound calls for appointment validation are covered in `07-APPOINTMENTS.md` Section 6. Outbound campaigns for general purposes are covered in `09-OUTBOUND-CAMPAIGNS.md`.
+
+---
+
+## 3. Post-Call Processing Pipeline
+
+Every completed call (inbound or outbound) triggers a post-call webhook from ElevenLabs. The system processes this webhook through a multi-step pipeline.
+
+### 3.1 Sequence Diagram
+
+```
+ElevenLabs                Webhook Controller       BullMQ Queue           Webhook Processor
+    |                            |                      |                        |
+    |  POST /webhooks/           |                      |                        |
+    |  elevenlabs                |                      |                        |
+    |  {conversation_id,         |                      |                        |
+    |   agent_id, transcript,    |                      |                        |
+    |   metadata, analysis}      |                      |                        |
+    |--------------------------->|                      |                        |
+    |                            |                      |                        |
+    |                            |  Validate payload    |                        |
+    |                            |  Enqueue job ------->|                        |
+    |  200 OK                    |                      |                        |
+    |<---------------------------|                      |                        |
+    |                            |                      |                        |
+    |                            |                      |  Dequeue job           |
+    |                            |                      |--------------------->  |
+    |                            |                      |                        |
+    |                            |                      |         Processor      |
+    |                            |                      |         Steps:         |
+    |                            |                      |                        |
+    |                            |                      |    1. Find Agent by    |
+    |                            |                      |       elevenlabs_id    |
+    |                            |                      |                        |
+    |                            |                      |    2. Resolve Clinic   |
+    |                            |                      |       from caller/     |
+    |                            |                      |       callee phone     |
+    |                            |                      |                        |
+    |                            |                      |    3. Generate AI      |
+    |                            |                      |       summary          |
+    |                            |                      |       (AIModule)       |
+    |                            |                      |                        |
+    |                            |                      |    4. Create Call +    |
+    |                            |                      |       CallDetail       |
+    |                            |                      |       records          |
+    |                            |                      |                        |
+    |                            |                      |    5. Generate labels  |
+    |                            |                      |       (sentiment,      |
+    |                            |                      |       categories)      |
+    |                            |                      |                        |
+    |                            |                      |    6. Log billing      |
+    |                            |                      |       charge           |
+    |                            |                      |                        |
+    |                            |                      |    7. Create Lead if   |
+    |                            |                      |       criteria met     |
+    |                            |                      |                        |
+    |                            |                      |    8. Send WhatsApp    |
+    |                            |                      |       notification     |
+    |                            |                      |                        |
+    |                            |                      |    9. Send SMS         |
+    |                            |                      |       notification     |
+    |                            |                      |                        |
+```
+
+### 3.2 Pipeline Steps in Detail
+
+#### Step 1: Find Agent by `elevenlabs_id`
+
+The webhook payload contains an `agent_id` (the ElevenLabs agent ID). Look up the internal `Agent` record via `agent_elevenlabs_id`. If not found, log a warning and discard the webhook (may be a test or deleted agent).
+
+#### Step 2: Resolve Clinic from Phone Number
+
+For inbound calls: match `caller_number` or `callee_number` against the `phone_numbers` table to find which `clinic_id` the call belongs to. The callee number (the number that was called) is typically the clinic's inbound line.
+
+For outbound calls: the originating phone number maps to a clinic via `phone_numbers.phone_clinic_id`.
+
+#### Step 3: Generate AI Summary
+
+Use the custom AIModule to generate a summary of the call transcript. The prompt is agent-specific: `agent.agent_summary_prompt` if set, otherwise a default prompt.
+
+```
+AIService.generateText({
+  system: agent.agent_summary_prompt || defaultSummaryPrompt,
+  prompt: transcript,
+  maxTokens: 500,
+  temperature: 0.3,
+  tenantAiProvider: tenant.tenant_default_ai_provider,
+})
+```
+
+The summary is a concise description of what was discussed, patient intent, and any actions taken (appointments booked, information requested, etc.).
+
+#### Step 4: Create Call and CallDetail Records
+
+The call metadata and heavy content are stored in separate tables for query performance.
+
+**calls table (metadata -- loaded on list views):**
+
+```
+call_id                    UUID PK
+call_tenant_id             UUID FK -> tenants
+call_clinic_id             UUID FK -> clinics       -- Required. Resolved from phone number (inbound) or campaign (outbound).
+call_patient_id            UUID? FK -> patients     -- Resolved by phone match during post-call processing.
+call_agent_id              UUID FK -> agents
+call_campaign_id           UUID? FK -> outbound_campaigns (null for non-campaign calls)
+call_conversation_id       String? -- ElevenLabs conversation ID
+call_direction             enum: inbound | outbound
+call_caller_number         String
+call_callee_number         String
+call_duration_seconds      Int
+call_start_time            DateTime?
+call_end_time              DateTime?
+call_termination_reason    String?
+call_cost                  Decimal?
+call_language              String?
+call_elevenlabs_status     String?
+call_status                enum: completed | failed | no_answer | voicemail | transferred
+call_sentiment             enum: positive | neutral | negative (nullable)
+call_categories            String[]
+call_wa_notification_sent  Boolean default false
+call_created_at            DateTime
+call_updated_at            DateTime
+```
+
+**call_details table (heavy content -- loaded on single call view):**
+
+```
+detail_id              UUID PK
+detail_call_id         UUID UNIQUE FK -> calls (CASCADE)
+detail_transcript      String
+detail_llm_summary     String?
+detail_extracted_data  JSONB?          -- AI-extracted structured data
+detail_recording_url   String?         -- External recording URL
+detail_recording_key   String?         -- MinIO key (if mirrored locally)
+detail_analysis        JSONB?          -- ElevenLabs analysis payload
+detail_created_at      DateTime
+detail_updated_at      DateTime
+```
+
+**Why split into two tables:** List queries (`GET /calls`) fetch only the `calls` table, which is lightweight -- no transcript or recording data. The `call_details` table is loaded only when viewing a single call (`GET /calls/:id`). At scale (thousands of calls per tenant), this keeps list queries fast.
+
+#### Step 5: Generate Labels (Sentiment and Categories)
+
+A second AI call classifies the conversation:
+
+```
+AIService.generateJson({
+  system: "Classify this conversation...",
+  prompt: transcript,
+  schema: {
+    sentiment: { type: "string", enum: ["positive", "neutral", "negative"] },
+    categories: { type: "array", items: { type: "string" } }
+  }
+})
+```
+
+Categories are free-form strings like `["randevu", "fiyat_sorgusu", "sikayet"]`. Sentiment is stored on the `calls` record for filtering in the dashboard.
+
+#### Step 6: Log Billing Charge
+
+Create a `BillingEvent` record:
+
+```
+billing_events:
+  billing_type   = 'call_charge'
+  billing_amount = duration_seconds / 60 * RATE_PER_MINUTE  -- 1.5 TRY/min
+  billing_call_id = call.call_id
+```
+
+This feeds into the tenant's usage dashboard and billing period snapshots.
+
+#### Step 7: Create Lead if Criteria Met
+
+Evaluate whether the call should generate a lead. Criteria are based on the AI analysis:
+- Patient expressed interest in a service
+- Patient requested a callback
+- Patient asked about pricing
+
+If criteria are met, create a `Lead` record linked to the call:
+
+```
+leads:
+  lead_call_id             = call.call_id
+  lead_clinic_id           = call.call_clinic_id
+  lead_name                = extracted patient name
+  lead_phone               = caller/callee phone
+  lead_service_of_interest = extracted from transcript
+  lead_summary             = AI-generated lead summary
+  lead_categories          = call categories
+  lead_status              = 'new_lead'
+```
+
+#### Step 8: Send WhatsApp Notification
+
+If `agent.agent_post_call_wa_notify` is true, send a summary notification to configured staff via WhatsApp. Uses `MetaWhatsAppService` (Meta Business API).
+
+The message template is `agent.agent_wa_message_template` or a default format:
+
+```
+Yeni arama ozeti:
+Arayan: {caller_number}
+Sure: {duration} dk
+Ozet: {summary}
+```
+
+#### Step 9: Send SMS Notification
+
+If `agent.agent_post_call_sms_notify` is true, send a brief SMS notification to `tenant.tenant_sms_phones` via NetGSM. **Note:** NetGSM integration is currently a stub -- SMS notifications are deferred.
+
+#### Step 10: Emit Events
+
+After all processing, emit events for the real-time WebSocket gateway:
+- `call:completed` -- pushes to frontend dashboard for live updates.
+- `lead:new` -- if a lead was created.
+
+---
+
+## 4. Webhook Tool Calls During Voice Calls
+
+During an active voice call, the ElevenLabs AI agent can invoke server-side tools via HTTP webhooks. These are separate from the post-call webhook.
+
+### 4.1 Endpoint
+
+```
+POST /webhooks/elevenlabs/tools/:toolName
+Headers:
+  x-api-key: {ELEVENLABS_WEBHOOK_SECRET}
+  x-agent-id: {elevenlabs_agent_id}      -- used to resolve tenant
+```
+
+### 4.2 Tenant Resolution
+
+The webhook does not carry a JWT. Tenant is resolved by:
+1. Read `agent_id` from the request headers or body.
+2. Look up `Agent` by `agent_elevenlabs_id`.
+3. Agent belongs to a tenant, which provides the `ToolContext`.
+
+### 4.3 Available Tools for Voice Calls
+
+| Tool | Description |
+|------|-------------|
+| `check_availability` | Check available appointment slots (local calendar is source of truth; Google Calendar is optional sync) |
+| `reserve_slot` | Book an appointment (writes to local calendar; optionally syncs to Google Calendar) |
+| `list_reservations` | List patient's appointments from local database |
+| `cancel_reservation` | Cancel an appointment locally (sync to Google Calendar if connected) |
+| `reschedule_reservation` | Reschedule an appointment locally (sync to Google Calendar if connected) |
+| `check_patient_history` | Look up patient profile and history |
+| `confirm_appointment_validation` | Record validation batch call result |
+
+All tools go through the generalized ToolRegistryService and ElevenLabsHttpAdapter. The tool handler code is shared with WhatsApp chat tools -- only the adapter layer differs.
+
+### 4.4 Authentication
+
+The webhook is authenticated via `x-api-key` header matching the `ELEVENLABS_WEBHOOK_SECRET` environment variable. This is a shared secret between the system and ElevenLabs.
+
+---
+
+## 5. Data Model Summary
+
+### calls
+
+Primary index for list queries. Lightweight -- no transcript or heavy content.
+
+```
+Indexes:
+  (call_tenant_id, call_created_at DESC)        -- tenant-scoped list
+  (call_clinic_id, call_created_at DESC)         -- clinic-scoped list
+  (call_campaign_id, call_status)                -- campaign call tracking
+  (call_tenant_id, call_direction, call_created_at DESC) -- direction filter
+  (call_conversation_id)                         -- webhook lookup
+  (call_tenant_id, call_callee_number)           -- phone number lookup
+  (call_patient_id)                              -- patient call history
+```
+
+### call_details
+
+One-to-one with calls. Loaded only on single call detail view.
+
+```
+Indexes:
+  (detail_call_id) UNIQUE                        -- FK to calls
+```
+
+### phone_numbers (inbound_call purpose)
+
+```
+Indexes:
+  (phone_tenant_id, phone_purpose)               -- filter by purpose
+  (phone_clinic_id)                              -- clinic lookup
+  (phone_provider, phone_external_account_id)    -- provider lookup
+```
+
+### BullMQ Queues
+
+| Queue | Purpose | Concurrency | Schedule |
+|-------|---------|-------------|----------|
+| `elevenlabs:webhook` | Post-call webhook processing pipeline | 5 | On webhook receipt |
+| `elevenlabs:tools` | Tool call webhook processing | 5 | On webhook receipt |
+| `inbound-call:schedule-sync` | Agent assignment sync | 1 | Every 15 minutes |
+
+### API Endpoints
+
+**Calls:**
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/calls` | `calls:read` | Paginated list (filterable by direction, status, agent, date range) |
+| GET | `/calls/stats` | `calls:read` | Aggregate statistics |
+| GET | `/calls/:id` | `calls:read` | Call detail with transcript and summary |
+
+**Phone numbers (inbound call):**
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/phone-numbers` | `phone_numbers:read` | List (filter by purpose=inbound_call) |
+| PUT | `/phone-numbers/:id/schedule` | `phone_numbers:manage` | Update inbound call schedule |
+| POST | `/phone-numbers/:id/toggle-agent` | `phone_numbers:manage` | Manual assign/unassign agent |
+
+**Webhooks (unauthenticated, API-key protected):**
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | `/webhooks/elevenlabs` | None (raw body) | Post-call webhook, enqueued to BullMQ |
+| POST | `/webhooks/elevenlabs/tools/:toolName` | x-api-key | Tool call during active voice call |
+
+### Feature Flags
+
+| Flag | Gates |
+|------|-------|
+| `inbound_agent` | Inbound call handling |
+| `inbound_call_schedule` | Schedule-based agent assignment |