elevenlabs-webhook-nodejs 1.0.0

package/docs/architecture/09-OUTBOUND-CAMPAIGNS.md

@@ -0,0 +1,542 @@
+# Outbound Campaigns
+
+> Customizable outbound call system for any use case: patient follow-ups, satisfaction surveys, marketing, feedback collection.
+> Last updated: 2026-04-02
+
+---
+
+## 1. Design Philosophy
+
+The outbound campaign system is intentionally decoupled from any specific use case. Earlier iterations tied campaigns to a Survey model with fixed questions. That dependency has been removed.
+
+**Core principle:** Each campaign defines its own prompt, first message, extraction schema, and schedule. The system does not know or care whether the campaign is a patient satisfaction survey, a follow-up call, or a marketing outreach. The extraction schema replaces fixed survey questions with flexible structured data extraction.
+
+**Comparison with Appointment Validation:**
+
+| Aspect | Appointment Validation | Outbound Campaigns |
+|--------|----------------------|-------------------|
+| Purpose | Confirm existing appointments | Any use case |
+| Outcomes | Fixed: confirmed, cancelled, reschedule, unresolved | Flexible: defined by extraction schema |
+| Data model | Batch + entries | Campaign + entries |
+| Agent config | Uses tenant's configured validation agent | Per-campaign custom prompt and voice |
+| Phone list source | CSV with appointment data columns | CSV/JSON with optional custom data per entry |
+| AI behavior | Single tool (`confirm_appointment_validation`) | Post-call extraction from transcript |
+| Feature flag | `appointment_validation` | `outbound_campaigns` |
+
+---
+
+## 2. Campaign Lifecycle
+
+### 2.1 State Machine
+
+```
+                  +-------+
+                  | draft |
+                  +---+---+
+                      |
+                      | start
+                      v
+                +-----------+
+                | scheduled |
+                +-----+-----+
+                      |
+                      | first call dispatched
+                      v
+                 +---------+
+            +--->| running |<---+
+            |    +----+----+    |
+            |         |         |
+            | resume  | pause   | resume
+            |         v         |
+            |    +--------+     |
+            +----| paused |-----+
+                 +--------+
+                      |
+                      | stop (or all entries done)
+                      v
+                +-----------+
+                | completed |
+                +-----------+
+```
+
+### 2.2 State Transitions
+
+| From | To | Trigger | Validation |
+|------|----|---------|-----------|
+| `draft` | `scheduled` | `POST /:id/start` | Must have entries, agent config, and schedule |
+| `draft` | (deleted) | `DELETE /:id` | Only draft campaigns can be deleted |
+| `scheduled` | `running` | First call dispatched by BullMQ | Automatic |
+| `running` | `paused` | `POST /:id/pause` | Stops dispatching new calls; in-progress calls continue |
+| `paused` | `running` | `POST /:id/resume` | Resumes dispatching |
+| `running` | `completed` | `POST /:id/stop` or all entries processed | Manual stop or automatic on completion |
+| `paused` | `completed` | `POST /:id/stop` | Manual stop while paused |
+
+**Constraints:**
+- Only `draft` campaigns can be edited (`PUT /:id`) or deleted.
+- Entries can only be uploaded (`POST /:id/entries`) or cleared (`DELETE /:id/entries`) while in `draft`.
+- Failed/no_answer entries can be retried in `running` or `paused` state.
+
+---
+
+## 3. Creating a Campaign
+
+### 3.1 Agent Configuration
+
+Each campaign carries its own agent configuration in the `campaign_agent_config` JSONB column:
+
+```typescript
+{
+  prompt: string;               // System prompt for the AI agent
+  first_message: string;        // What the AI says when the patient answers
+  language: string;             // e.g., "tr"
+  voice_id: string;             // ElevenLabs voice ID
+  extraction_schema: Array<{    // What data to extract (Section 4)
+    field: string;
+    type: 'text' | 'number' | 'boolean' | 'enum';
+    description: string;
+    options?: string[];          // Required for enum type
+    required: boolean;
+  }>;
+  post_call_prompt: string;     // Prompt for post-call data extraction
+}
+```
+
+The `campaign_agent_id` references the base Agent record (for ElevenLabs agent ID and tenant resolution), but the prompt and voice can be overridden per-campaign via `agent_config`.
+
+### 3.2 Phone List Upload
+
+Entries are uploaded as CSV or JSON. Each entry can carry optional custom data that is passed to the AI agent as dynamic variables during the call.
+
+```
+POST /outbound-campaigns/:id/entries
+Content-Type: application/json
+
+{
+  "entries": [
+    {
+      "phone": "+905551234567",
+      "contact_name": "Ayse Yilmaz",
+      "custom_data": {
+        "product": "Implant",
+        "last_visit": "2026-01-15",
+        "doctor": "Dr. Mehmet"
+      }
+    },
+    ...
+  ]
+}
+```
+
+The `custom_data` is stored in `centry_custom_data` (JSONB) and made available to the AI agent as dynamic variables during the call. This enables personalized conversations without changing the campaign prompt.
+
+### 3.3 Schedule Configuration
+
+Stored in `campaign_schedule` JSONB:
+
+```typescript
+{
+  start_date: string;           // "2026-04-01"
+  end_date: string;             // "2026-04-15"
+  daily_start_time: string;     // "09:00"
+  daily_end_time: string;       // "18:00"
+  days_of_week: number[];       // [1,2,3,4,5] (Mon-Fri)
+  max_concurrent: number;       // Max simultaneous calls (e.g., 5)
+  max_retries: number;          // Max retry attempts per entry (e.g., 3)
+  retry_delay_minutes: number;  // Delay between retries (e.g., 60)
+}
+```
+
+---
+
+## 4. Extraction Schema
+
+The extraction schema defines what structured data the AI should pull from each call. It replaces fixed survey questions with a flexible, per-campaign definition.
+
+### 4.1 Schema Definition
+
+```typescript
+extraction_schema: [
+  {
+    field: "satisfaction_score",
+    type: "number",
+    description: "Patient's satisfaction on a scale of 1-10",
+    required: true
+  },
+  {
+    field: "wants_callback",
+    type: "boolean",
+    description: "Whether the patient wants to be called back",
+    required: true
+  },
+  {
+    field: "preferred_time",
+    type: "enum",
+    description: "When the patient prefers to be contacted",
+    options: ["morning", "afternoon", "evening", "no_preference"],
+    required: false
+  },
+  {
+    field: "feedback",
+    type: "text",
+    description: "Free-form patient feedback about their experience",
+    required: false
+  }
+]
+```
+
+### 4.2 Supported Types
+
+| Type | Description | Example Value |
+|------|-------------|---------------|
+| `text` | Free-form string | `"The service was excellent but parking was difficult"` |
+| `number` | Numeric value | `8` |
+| `boolean` | True or false | `true` |
+| `enum` | One of predefined options | `"morning"` |
+
+### 4.3 Extraction Process
+
+Data extraction happens during post-call processing (Section 6), not during the call itself. The AI processes the transcript with a dedicated extraction prompt (`agent_config.post_call_prompt`) that references the schema:
+
+```
+Given this phone call transcript, extract the following data points:
+- satisfaction_score (number, 1-10): Patient's satisfaction rating
+- wants_callback (boolean): Whether patient wants callback
+- preferred_time (enum: morning/afternoon/evening/no_preference): Contact preference
+- feedback (text): Free-form patient feedback
+
+Transcript:
+{transcript}
+
+Return valid JSON matching the schema.
+```
+
+The extracted data is stored as JSONB in `centry_extracted_data`:
+
+```json
+{
+  "satisfaction_score": 8,
+  "wants_callback": true,
+  "preferred_time": "morning",
+  "feedback": "The treatment was great but I had to wait 30 minutes"
+}
+```
+
+---
+
+## 5. Call Dispatch (BullMQ)
+
+### 5.1 Dispatch Processor
+
+**Queue:** `outbound-campaigns:dispatch`
+**Concurrency:** Configured per-campaign via `campaign_schedule.max_concurrent`.
+
+### 5.2 Dispatch Flow
+
+```
+Campaign started (status = scheduled/running)
+  |
+  v
+Dispatch processor picks up campaign
+  |
+  v
+For each entry where centry_status = 'pending'
+  AND centry_attempts < centry_max_attempts:
+  |
+  +-- Check time window
+  |     |
+  |     +-- Current time within daily_start_time..daily_end_time?
+  |     +-- Current day in days_of_week?
+  |     +-- Current date within start_date..end_date?
+  |     |
+  |     +-- NO: delay job until next valid window
+  |     +-- YES: continue
+  |
+  +-- Check concurrency
+  |     |
+  |     +-- Count entries where centry_status = 'calling'
+  |     +-- If count >= max_concurrent: wait
+  |
+  +-- Dispatch call
+        |
+        1. Set centry_status = 'calling'
+        2. Set centry_attempts += 1
+        3. Set centry_last_attempt_at = now()
+        4. Call elevenlabsService.sipTrunkOutboundCall({
+             agentId: campaign.agent.agent_elevenlabs_id,
+             fromPhoneNumber: campaign.phone.phone_number,
+             toPhoneNumber: centry_phone,
+             dynamicVariables: {
+               contact_name: centry_contact_name,
+               ...centry_custom_data
+             },
+             agentOverrides: {
+               prompt: campaign_agent_config.prompt,
+               first_message: campaign_agent_config.first_message,
+               language: campaign_agent_config.language,
+               voice_id: campaign_agent_config.voice_id,
+             }
+           })
+        5. On success: store conversation_id in centry_conversation_id
+        6. On failure: set centry_status = 'failed'
+           If attempts < max_retries: requeue with retry_delay_minutes
+```
+
+### 5.3 Time Window Enforcement
+
+Calls are only placed during the configured schedule window. If the dispatch processor runs outside the window, it calculates the delay to the next valid window and schedules the job accordingly:
+
+```
+next_window = find next valid {day_of_week + daily_start_time} from now
+delay = next_window - Date.now()
+queue.add('dispatch', { campaignId, entryId }, { delay })
+```
+
+### 5.4 Retry Logic
+
+| Scenario | Action |
+|----------|--------|
+| Call placed, no answer | Set status `no_answer`. If attempts < max_retries, requeue with delay. |
+| Call placed, voicemail | Set status `voicemail`. If attempts < max_retries, requeue with delay. |
+| Call failed (SIP error) | Set status `failed`. If attempts < max_retries, requeue with delay. |
+| Call completed | Proceed to post-call processing. |
+| Max attempts exhausted | Set final status. No more retries. |
+
+Manual retry is also available via:
+- `POST /:id/retry` -- retry all failed/no_answer entries in the campaign.
+- `POST /:id/entries/:entryId/retry` -- retry a single entry.
+
+---
+
+## 6. Post-Call Processing
+
+### 6.1 Sequence Diagram
+
+```
+ElevenLabs           Webhook Handler         Webhook Processor           AIModule             Database
+    |                       |                       |                       |                    |
+    |  Post-call webhook    |                       |                       |                    |
+    |  {conversation_id,    |                       |                       |                    |
+    |   transcript, ...}    |                       |                       |                    |
+    |---------------------->|                       |                       |                    |
+    |                       |                       |                       |                    |
+    |                       |  Enqueue to           |                       |                    |
+    |                       |  elevenlabs:webhook   |                       |                    |
+    |  200 OK               |  queue                |                       |                    |
+    |<----------------------|                       |                       |                    |
+    |                       |                       |                       |                    |
+    |                       |                       |  Process job           |                    |
+    |                       |                       |                       |                    |
+    |                       |                       |  1. Find campaign      |                    |
+    |                       |                       |     entry by           |                    |
+    |                       |                       |     conversation_id    |                    |
+    |                       |                       |                       |                    |
+    |                       |                       |  2. Extract data per   |                    |
+    |                       |                       |     extraction_schema  |                    |
+    |                       |                       |---------------------->|                    |
+    |                       |                       |  extracted_data JSON   |                    |
+    |                       |                       |<----------------------|                    |
+    |                       |                       |                       |                    |
+    |                       |                       |  3. Generate summary   |                    |
+    |                       |                       |---------------------->|                    |
+    |                       |                       |  summary text          |                    |
+    |                       |                       |<----------------------|                    |
+    |                       |                       |                       |                    |
+    |                       |                       |  4. Update entry       |                    |
+    |                       |                       |     status, data,      |                    |
+    |                       |                       |     summary            |                    |
+    |                       |                       |--------------------------------------------->|
+    |                       |                       |                       |                    |
+    |                       |                       |  5. Create Call        |                    |
+    |                       |                       |     record, link to    |                    |
+    |                       |                       |     entry              |                    |
+    |                       |                       |--------------------------------------------->|
+    |                       |                       |                       |                    |
+    |                       |                       |  6. Recalculate        |                    |
+    |                       |                       |     campaign_stats     |                    |
+    |                       |                       |--------------------------------------------->|
+    |                       |                       |                       |                    |
+```
+
+### 6.2 Processing Steps
+
+1. **Match entry by `conversation_id`:** The ElevenLabs webhook contains a `conversation_id`. Look up the `OutboundCampaignEntry` where `centry_conversation_id` matches.
+
+2. **Extract structured data:** Use AIModule with the campaign's `post_call_prompt` and `extraction_schema` to pull structured data from the transcript. Store the result as JSONB in `centry_extracted_data`.
+
+3. **Generate summary:** Use AIModule to produce a concise text summary of the call. Store in `centry_summary`.
+
+4. **Update entry:** Set `centry_status = 'completed'`, `centry_call_duration_secs`, `centry_completed_at = now()`.
+
+5. **Create Call record:** Insert a row in the `calls` table with `call_campaign_id` linking back to the campaign. Insert `call_details` with transcript and summary. Link the call to the entry via `centry_call_id`.
+
+6. **Recalculate campaign stats:** Update the denormalized `campaign_stats` JSON by counting entries per status:
+   ```json
+   {
+     "total": 150,
+     "pending": 42,
+     "calling": 3,
+     "completed": 89,
+     "failed": 8,
+     "no_answer": 6,
+     "voicemail": 2
+   }
+   ```
+   This avoids expensive aggregation queries on every dashboard load.
+
+---
+
+## 7. Data Model
+
+### outbound_campaigns
+
+```
+outbound_campaigns
+  campaign_id              UUID PK
+  campaign_tenant_id       UUID FK -> tenants
+  campaign_clinic_id       UUID FK -> clinics      -- Required. Every campaign belongs to a clinic.
+  campaign_agent_id        UUID FK -> agents
+  campaign_name            String
+  campaign_description     String
+  campaign_status          enum: draft | scheduled | running | paused | completed
+  campaign_agent_config    JSONB    -- {prompt, first_message, language, voice_id,
+                                   --  extraction_schema, post_call_prompt}
+  campaign_schedule        JSONB    -- {start_date, end_date, daily_start_time,
+                                   --  daily_end_time, days_of_week, max_concurrent,
+                                   --  max_retries, retry_delay_minutes}
+  campaign_phone_id        UUID? FK -> phone_numbers (outbound phone)
+  campaign_stats           JSONB    -- {total, pending, calling, completed, failed, ...}
+  campaign_created_at      DateTime
+  campaign_updated_at      DateTime
+
+  Indexes:
+    (campaign_tenant_id, campaign_status)
+    (campaign_clinic_id)
+```
+
+### outbound_campaign_entries
+
+```
+outbound_campaign_entries
+  centry_id                UUID PK
+  centry_campaign_id       UUID FK -> outbound_campaigns (CASCADE)
+  centry_phone             String
+  centry_contact_name      String
+  centry_custom_data       JSONB default {}    -- Per-entry dynamic variables
+  centry_status            enum: pending | calling | completed | failed | no_answer | voicemail
+  centry_attempts          Int default 0
+  centry_max_attempts      Int default 3
+  centry_last_attempt_at   DateTime?
+  centry_conversation_id   String?             -- ElevenLabs conversation ID
+  centry_call_id           UUID? FK -> calls   -- Linked after call completes
+  centry_call_duration_secs Int default 0
+  centry_extracted_data    JSONB?              -- AI-extracted per extraction_schema
+  centry_summary           String?
+  centry_called_at         DateTime?
+  centry_completed_at      DateTime?
+  centry_created_at        DateTime
+  centry_updated_at        DateTime
+
+  Indexes:
+    (centry_campaign_id, centry_status)
+    (centry_conversation_id)
+```
+
+### campaign_stats (Denormalized)
+
+The `campaign_stats` JSONB on `outbound_campaigns` is a cache. It is recomputed whenever an entry status changes (in the post-call processor and dispatch processor). This avoids `COUNT(*)` queries with GROUP BY on every dashboard page load.
+
+Recomputation logic:
+
+```sql
+SELECT centry_status, COUNT(*) as count
+FROM outbound_campaign_entries
+WHERE centry_campaign_id = :campaignId
+GROUP BY centry_status
+```
+
+The result is written to `campaign_stats` as a single JSON object.
+
+---
+
+## 8. API Endpoints
+
+| Method | Path | Permission | Description |
+|--------|------|-----------|-------------|
+| GET | `/outbound-campaigns` | `campaigns:read` | List campaigns (paginated) |
+| POST | `/outbound-campaigns` | `campaigns:manage` | Create campaign with agent config + extraction schema |
+| GET | `/outbound-campaigns/:id` | `campaigns:read` | Campaign detail with stats |
+| PUT | `/outbound-campaigns/:id` | `campaigns:manage` | Update (only in draft) |
+| DELETE | `/outbound-campaigns/:id` | `campaigns:manage` | Delete (only in draft) |
+| POST | `/outbound-campaigns/:id/entries` | `campaigns:manage` | Upload phone list |
+| DELETE | `/outbound-campaigns/:id/entries` | `campaigns:manage` | Clear phone list (only in draft) |
+| POST | `/outbound-campaigns/:id/start` | `campaigns:manage` | Start calling |
+| POST | `/outbound-campaigns/:id/pause` | `campaigns:manage` | Pause calling |
+| POST | `/outbound-campaigns/:id/resume` | `campaigns:manage` | Resume calling |
+| POST | `/outbound-campaigns/:id/stop` | `campaigns:manage` | Stop and complete |
+| POST | `/outbound-campaigns/:id/retry` | `campaigns:manage` | Retry all failed/no_answer |
+| POST | `/outbound-campaigns/:id/entries/:entryId/retry` | `campaigns:manage` | Retry single entry |
+| GET | `/outbound-campaigns/:id/results` | `campaigns:read` | Results with extracted data |
+| GET | `/outbound-campaigns/:id/results/export` | `campaigns:export` | CSV export with extracted data |
+| GET | `/outbound-campaigns/:id/logs` | `campaigns:read` | Campaign-scoped application logs |
+| POST | `/outbound-campaigns/:id/sync` | `campaigns:manage` | Manual sync statuses from ElevenLabs |
+
+### CSV Export Format
+
+The export includes all static entry fields plus dynamically generated columns from the extraction schema:
+
+```
+Phone, Contact Name, Status, Attempts, Call Duration, Called At, Completed At,
+Summary, [extraction_field_1], [extraction_field_2], ...
+```
+
+For example, with the satisfaction survey schema from Section 4.1:
+
+```
+Phone, Contact Name, Status, ..., satisfaction_score, wants_callback, preferred_time, feedback
++905551234567, Ayse Yilmaz, completed, ..., 8, true, morning, "Great service but parking..."
+```
+
+---
+
+## 9. BullMQ Queues
+
+| Queue | Purpose | Concurrency | Schedule |
+|-------|---------|-------------|----------|
+| `outbound-campaigns:dispatch` | Call dispatch with time window enforcement | Per-campaign `max_concurrent` | On campaign start, continuous |
+| `outbound-campaigns:sync` | Sync entry statuses from ElevenLabs | 1 | Repeatable every 60 seconds |
+
+The dispatch processor runs as a continuous loop while a campaign is in `running` status. It picks the next `pending` entry, checks time window constraints, and dispatches the call. When paused, the processor stops picking new entries but does not interrupt in-progress calls.
+
+The sync processor polls ElevenLabs for conversation statuses, similar to appointment validation sync. It handles edge cases where the post-call webhook was missed or delayed.
+
+---
+
+## 10. Feature Flag
+
+| Flag | Gates |
+|------|-------|
+| `outbound_campaigns` | All `/outbound-campaigns/*` endpoints |
+
+The feature flag is checked by the `FeaturesGuard` on every request to the outbound campaigns controller. If the tenant does not have `outbound_campaigns` in `tenant_enabled_features`, all endpoints return 403.
+
+---
+
+## 11. NestJS Module Structure
+
+```
+src/outbound-campaigns/
+  outbound-campaigns.module.ts       -- Module definition, imports BullMQ queues
+  outbound-campaigns.controller.ts   -- All REST endpoints
+  outbound-campaigns.service.ts      -- Business logic: create, start, pause, stop, retry, sync
+  processors/
+    dispatch.processor.ts            -- BullMQ: call dispatch with concurrency + time windows
+    sync.processor.ts                -- BullMQ: status sync from ElevenLabs
+```
+
+The module imports:
+- `IntegrationsModule` (for `ElevenLabsService` -- SIP trunk outbound calls)
+- `AIModule` (for post-call extraction and summary)
+- `BullModule.registerQueue('outbound-campaigns:dispatch', 'outbound-campaigns:sync')`
+- `PrismaModule` (for database access)
+
+The post-call processing for campaign entries is handled within the `elevenlabs:webhook` processor (shared with all call types), which detects campaign calls by checking if a `conversation_id` matches any `centry_conversation_id`.