elevenlabs-webhook-nodejs 1.0.0

package/docs/API.md

@@ -0,0 +1,1193 @@
+# API Reference
+
+All protected routes require `Authorization: Bearer <access_token>` header.
+All routes are **tenant-scoped** — users can only access data belonging to their own tenant.
+
+For auth endpoints (register, login, refresh, logout, me), see [AUTH_API.md](./AUTH_API.md).
+
+---
+
+## Tenants
+
+Base URL: `/tenants`
+
+All routes require authentication.
+
+### GET /tenants/me
+
+Returns the current user's tenant details.
+
+**Auth:** Bearer token
+**Roles:** any
+
+**200 OK:**
+
+```json
+{
+  "tenant": {
+    "id": "664f1a...",
+    "name": "Acme Corp",
+    "plan": "free",
+    "enabled_features": ["inbound_agent", "whatsapp_notifications"],
+    "settings": {
+      "kvkk_consent": false,
+      "notification_recipients": [],
+      "default_language": "tr"
+    },
+    "createdAt": "2025-01-15T10:00:00.000Z"
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 401 | Missing or invalid token |
+| 404 | Tenant not found |
+
+---
+
+### PUT /tenants/me
+
+Updates tenant name and/or settings. Only provided fields are updated.
+
+**Auth:** Bearer token
+**Roles:** `admin`
+
+**Request Body:**
+
+```json
+{
+  "name": "New Company Name",
+  "settings": {
+    "kvkk_consent": true,
+    "notification_recipients": ["+905551234567"],
+    "default_language": "en"
+  }
+}
+```
+
+All fields are optional. Only include the ones you want to change.
+
+**200 OK:**
+
+```json
+{
+  "tenant": {
+    "id": "664f1a...",
+    "name": "New Company Name",
+    "plan": "free",
+    "enabled_features": ["inbound_agent", "whatsapp_notifications"],
+    "settings": {
+      "kvkk_consent": true,
+      "notification_recipients": ["+905551234567"],
+      "default_language": "en"
+    }
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | No valid fields provided |
+| 403 | Not an admin |
+| 404 | Tenant not found |
+
+---
+
+## Users
+
+Base URL: `/users`
+
+All routes require authentication. Users are scoped to the authenticated user's tenant.
+
+### GET /users
+
+Lists all users in the current tenant.
+
+**Auth:** Bearer token
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "users": [
+    {
+      "_id": "664f1a...",
+      "tenant_id": "664f1a...",
+      "email": "user@example.com",
+      "role": "admin",
+      "name": "John Doe",
+      "createdAt": "2025-01-15T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+Note: `password_hash` is excluded from the response.
+
+---
+
+### POST /users/invite
+
+Creates a new user in the current tenant.
+
+**Auth:** Bearer token
+**Roles:** `admin`
+
+**Request Body:**
+
+```json
+{
+  "email": "newuser@example.com",
+  "password": "min8chars",
+  "name": "Jane Doe",
+  "role": "manager"
+}
+```
+
+**201 Created:**
+
+```json
+{
+  "user": {
+    "id": "664f1b...",
+    "email": "newuser@example.com",
+    "name": "Jane Doe",
+    "role": "manager",
+    "createdAt": "2025-01-15T10:00:00.000Z"
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing required fields |
+| 400 | Password shorter than 8 characters |
+| 400 | Invalid role (must be `admin`, `manager`, or `viewer`) |
+| 403 | Not an admin |
+| 409 | Email already registered |
+
+---
+
+### PUT /users/:id
+
+Updates a user's role and/or name.
+
+**Auth:** Bearer token
+**Roles:** `admin`
+
+**Request Body:**
+
+```json
+{
+  "role": "viewer",
+  "name": "Updated Name"
+}
+```
+
+Both fields are optional.
+
+**200 OK:**
+
+```json
+{
+  "user": {
+    "id": "664f1b...",
+    "email": "newuser@example.com",
+    "name": "Updated Name",
+    "role": "viewer"
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Invalid role |
+| 400 | Cannot change your own role |
+| 403 | Not an admin |
+| 404 | User not found in this tenant |
+
+---
+
+### DELETE /users/:id
+
+Removes a user from the tenant.
+
+**Auth:** Bearer token
+**Roles:** `admin`
+
+**200 OK:**
+
+```json
+{
+  "success": true
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Cannot delete yourself |
+| 403 | Not an admin |
+| 404 | User not found in this tenant |
+
+---
+
+## Calls
+
+Base URL: `/calls`
+
+All routes require authentication.
+
+### GET /calls
+
+Lists calls for the current tenant with pagination and filters.
+
+**Auth:** Bearer token
+**Roles:** `admin`, `manager`, `viewer`
+
+**Query Parameters:**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `page` | number | `1` | Page number |
+| `limit` | number | `20` | Items per page (max 100) |
+| `direction` | string | - | Filter: `inbound` or `outbound` |
+| `status` | string | - | Filter: `completed`, `failed`, `no_answer`, `voicemail`, `transferred` |
+| `agent_id` | string | - | Filter by agent ObjectId |
+| `from` | ISO date | - | Filter: calls after this date |
+| `to` | ISO date | - | Filter: calls before this date |
+
+**200 OK:**
+
+```json
+{
+  "calls": [
+    {
+      "_id": "664f1c...",
+      "tenant_id": "664f1a...",
+      "agent_id": {
+        "_id": "664f1b...",
+        "phone_number": "+902121234567",
+        "agent_template": "receptionist"
+      },
+      "direction": "inbound",
+      "caller_number": "+905551234567",
+      "callee_number": "+902121234567",
+      "duration_seconds": 120,
+      "status": "completed",
+      "llm_summary": "Arayan randevu almak istedi...",
+      "whatsapp_notification_sent": true,
+      "createdAt": "2025-01-15T10:00:00.000Z"
+    }
+  ],
+  "total": 42,
+  "page": 1,
+  "totalPages": 3
+}
+```
+
+Note: `transcript` field is excluded from list responses for performance. Use `GET /calls/:id` for full detail.
+
+---
+
+### GET /calls/stats
+
+Returns aggregated call statistics for the current tenant.
+
+**Auth:** Bearer token
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "stats": {
+    "total": 150,
+    "completed": 120,
+    "failed": 10,
+    "no_answer": 20,
+    "inbound": 100,
+    "outbound": 50,
+    "avg_duration": 95.5,
+    "total_duration": 14325
+  }
+}
+```
+
+---
+
+### GET /calls/:id
+
+Returns full call detail including transcript, summary, and survey responses.
+
+**Auth:** Bearer token
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "call": {
+    "_id": "664f1c...",
+    "tenant_id": "664f1a...",
+    "agent_id": {
+      "_id": "664f1b...",
+      "phone_number": "+902121234567",
+      "agent_template": "receptionist",
+      "config": { "voice_id": "abc123" }
+    },
+    "campaign_id": null,
+    "direction": "inbound",
+    "caller_number": "+905551234567",
+    "callee_number": "+902121234567",
+    "duration_seconds": 120,
+    "status": "completed",
+    "transcript": "Arayan: Merhaba, randevu almak istiyorum.\nAsistan: Tabii, hangi gun uygun?...",
+    "llm_summary": "Arayan randevu almak istedi. 15 Ocak saat 14:00 icin randevu olusturuldu.",
+    "survey_responses": null,
+    "whatsapp_notification_sent": true,
+    "recording_url": null,
+    "createdAt": "2025-01-15T10:00:00.000Z"
+  }
+}
+```
+
+When the call has survey responses (extract_survey strategy):
+
+```json
+{
+  "call": {
+    "...": "...",
+    "survey_responses": [
+      {
+        "question_id": "Q1",
+        "question_text": "Hizmetimizi 1-5 arasi nasil degerlendirirsiniz?",
+        "answer": "4",
+        "parsed_value": 4
+      }
+    ]
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Call not found in this tenant |
+
+---
+
+## Webhooks
+
+### POST /webhooks/elevenlabs
+
+Receives post-call data from ElevenLabs. Secured by HMAC-SHA256 signature verification (not JWT).
+
+**Auth:** `elevenlabs-signature` header (HMAC)
+
+**Behavior:**
+
+1. Returns `200 { "status": "received" }` immediately
+2. Processes the call asynchronously in the background:
+   - Looks up Agent by `elevenlabs_agent_id`
+   - Creates a Call record in the new data model
+   - Runs post-call processing based on `agent.post_call_processing.strategy`:
+
+| Strategy | Action |
+|----------|--------|
+| `summarize` | LLM generates summary → saved to `call.llm_summary` |
+| `extract_survey` | LLM extracts structured answers → saved to `call.survey_responses` |
+| `summarize_and_extract` | Both of the above |
+| `none` | Call saved with transcript only, no LLM processing |
+
+3. If `agent.post_call_processing.whatsapp_notify` is `true`, sends WhatsApp notification to matching recipients
+
+**Request Body (from ElevenLabs):**
+
+```json
+{
+  "type": "post_call_transcription",
+  "event_timestamp": 1705312800,
+  "data": {
+    "conversation_id": "conv_123",
+    "agent_id": "agent_abc",
+    "agent_name": "Receptionist",
+    "status": "done",
+    "transcript": [
+      { "role": "agent", "message": "Merhaba, nasil yardimci olabilirim?" },
+      { "role": "user", "message": "Randevu almak istiyorum." }
+    ],
+    "metadata": {
+      "call_duration_secs": 120,
+      "phone_call": { "external_number": "+905551234567" }
+    }
+  }
+}
+```
+
+**200 OK:**
+
+```json
+{
+  "status": "received"
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 401 | Invalid or missing HMAC signature |
+
+---
+
+## Surveys
+
+Base URL: `/surveys`
+
+All routes require authentication and the `survey_builder` feature.
+
+### GET /surveys
+
+Lists all surveys for the current tenant. Questions are excluded for performance.
+
+**Auth:** Bearer token
+**Feature:** `survey_builder`
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "surveys": [
+    {
+      "_id": "664f1d...",
+      "tenant_id": "664f1a...",
+      "name": "Musteri Memnuniyeti",
+      "description": "Hizmet sonrasi anket",
+      "status": "active",
+      "createdAt": "2025-01-15T10:00:00.000Z",
+      "updatedAt": "2025-01-16T08:00:00.000Z"
+    }
+  ]
+}
+```
+
+---
+
+### POST /surveys
+
+Creates a new survey in draft status.
+
+**Auth:** Bearer token
+**Feature:** `survey_builder`
+**Roles:** `admin`, `manager`
+
+**Request Body:**
+
+```json
+{
+  "name": "Musteri Memnuniyeti",
+  "description": "Hizmet sonrasi anket",
+  "questions": [
+    {
+      "id": "Q1",
+      "text": "Hizmetimizi 1-5 arasi nasil degerlendirirsiniz?",
+      "type": "rating",
+      "options": [],
+      "required": true,
+      "branch_logic": null
+    },
+    {
+      "id": "Q2",
+      "text": "Tekrar tercih eder misiniz?",
+      "type": "yes_no",
+      "options": [],
+      "required": true,
+      "branch_logic": {
+        "condition": "answer == 'no'",
+        "go_to": "Q3"
+      }
+    },
+    {
+      "id": "Q3",
+      "text": "Nedenini aciklar misiniz?",
+      "type": "open",
+      "options": [],
+      "required": false,
+      "branch_logic": null
+    }
+  ]
+}
+```
+
+`questions` is optional on creation — can be added later via PUT.
+
+**Question types:**
+
+| Type | Description |
+|------|-------------|
+| `open` | Free text answer |
+| `multiple_choice` | Must have 2+ options |
+| `rating` | Numeric rating |
+| `yes_no` | Yes/no answer |
+
+**Validation rules:**
+- Question IDs must be unique
+- `multiple_choice` questions must have at least 2 options
+- `branch_logic.go_to` must reference an existing question ID
+
+**201 Created:**
+
+```json
+{
+  "survey": {
+    "_id": "664f1d...",
+    "tenant_id": "664f1a...",
+    "name": "Musteri Memnuniyeti",
+    "status": "draft",
+    "questions": [ ... ]
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing name |
+| 400 | Question validation failed (see rules above) |
+| 403 | Feature not available / insufficient role |
+
+---
+
+### GET /surveys/:id
+
+Returns full survey detail including all questions.
+
+**Auth:** Bearer token
+**Feature:** `survey_builder`
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "survey": {
+    "_id": "664f1d...",
+    "name": "Musteri Memnuniyeti",
+    "description": "Hizmet sonrasi anket",
+    "status": "active",
+    "questions": [
+      {
+        "id": "Q1",
+        "text": "Hizmetimizi 1-5 arasi nasil degerlendirirsiniz?",
+        "type": "rating",
+        "options": [],
+        "required": true,
+        "branch_logic": null
+      }
+    ]
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Survey not found in this tenant |
+
+---
+
+### PUT /surveys/:id
+
+Updates survey fields. All body fields are optional.
+
+**Auth:** Bearer token
+**Feature:** `survey_builder`
+**Roles:** `admin`, `manager`
+
+**Request Body:**
+
+```json
+{
+  "name": "Updated Name",
+  "description": "Updated description",
+  "questions": [ ... ],
+  "status": "active"
+}
+```
+
+Status values: `draft`, `active`, `archived`.
+
+**200 OK:**
+
+```json
+{
+  "survey": { ... }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Question validation failed |
+| 404 | Survey not found |
+
+---
+
+### DELETE /surveys/:id
+
+Deletes a survey. Blocked if any active campaigns reference it.
+
+**Auth:** Bearer token
+**Feature:** `survey_builder`
+**Roles:** `admin`, `manager`
+
+**200 OK:**
+
+```json
+{
+  "success": true
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Survey not found |
+| 409 | Cannot delete survey with active campaigns (scheduled/running/paused) |
+
+---
+
+### POST /surveys/:id/duplicate
+
+Clones a survey as a new draft with "(kopya)" appended to the name.
+
+**Auth:** Bearer token
+**Feature:** `survey_builder`
+**Roles:** `admin`, `manager`
+
+**201 Created:**
+
+```json
+{
+  "survey": {
+    "_id": "664f1e...",
+    "name": "Musteri Memnuniyeti (kopya)",
+    "status": "draft",
+    "questions": [ ... ]
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Original survey not found |
+
+---
+
+## Campaigns
+
+Base URL: `/campaigns`
+
+All routes require authentication and the `outbound_campaigns` feature.
+
+### GET /campaigns
+
+Lists campaigns with pagination. Phone list is excluded for performance.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`, `viewer`
+
+**Query Parameters:**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `page` | number | `1` | Page number |
+| `status` | string | - | Filter: `draft`, `scheduled`, `running`, `paused`, `completed` |
+
+**200 OK:**
+
+```json
+{
+  "campaigns": [
+    {
+      "_id": "664f1e...",
+      "name": "Ocak Anketi",
+      "status": "running",
+      "survey_id": { "_id": "664f1d...", "name": "Musteri Memnuniyeti", "status": "active" },
+      "agent_id": { "_id": "664f1b...", "phone_number": "+902121234567", "agent_template": "survey" },
+      "schedule": { ... },
+      "stats": { "total": 100, "completed": 42, "failed": 3, "no_answer": 5, "voicemail": 0, "pending": 50 },
+      "createdAt": "2025-01-15T10:00:00.000Z"
+    }
+  ],
+  "total": 5,
+  "page": 1,
+  "totalPages": 1
+}
+```
+
+---
+
+### POST /campaigns
+
+Creates a new campaign in draft status. Validates that the referenced survey and agent belong to the current tenant.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`
+
+**Request Body:**
+
+```json
+{
+  "name": "Ocak Anketi",
+  "survey_id": "664f1d...",
+  "agent_id": "664f1b...",
+  "schedule": {
+    "start_date": "2025-02-01",
+    "end_date": "2025-02-28",
+    "daily_start_time": "09:00",
+    "daily_end_time": "18:00",
+    "days_of_week": [1, 2, 3, 4, 5],
+    "max_concurrent_calls": 3,
+    "max_retries": 3,
+    "retry_delay_minutes": 60
+  }
+}
+```
+
+Schedule defaults: `daily_start_time` = "09:00", `daily_end_time` = "18:00", `days_of_week` = [1-5], `max_concurrent_calls` = 1, `max_retries` = 3, `retry_delay_minutes` = 60.
+
+**201 Created:**
+
+```json
+{
+  "campaign": { ... }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Missing required fields |
+| 404 | Survey or agent not found in this tenant |
+
+---
+
+### GET /campaigns/:id
+
+Returns full campaign detail with populated survey and agent.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "campaign": {
+    "_id": "664f1e...",
+    "name": "Ocak Anketi",
+    "status": "running",
+    "survey_id": { "_id": "...", "name": "...", "status": "active", "questions": [ ... ] },
+    "agent_id": { "_id": "...", "phone_number": "...", "agent_template": "survey" },
+    "phone_list": [
+      { "number": "+905551234567", "status": "completed", "attempts": 1, "last_attempt_at": "..." },
+      { "number": "+905559876543", "status": "pending", "attempts": 0, "last_attempt_at": null }
+    ],
+    "schedule": { ... },
+    "stats": { ... }
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Campaign not found |
+
+---
+
+### PUT /campaigns/:id
+
+Updates campaign name and/or schedule. Only allowed in `draft` or `scheduled` status.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`
+
+**Request Body:**
+
+```json
+{
+  "name": "Updated Name",
+  "schedule": {
+    "daily_start_time": "10:00",
+    "max_concurrent_calls": 5
+  }
+}
+```
+
+**200 OK:**
+
+```json
+{
+  "campaign": { ... }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Campaign is not in draft or scheduled status |
+| 404 | Campaign not found |
+
+---
+
+### Campaign State Machine
+
+```
+draft → scheduled → running → paused → running (resume)
+                         ↓          ↓
+                     completed   completed
+```
+
+All state transition endpoints return `{ "campaign": { ... } }` on success.
+
+#### POST /campaigns/:id/start
+
+Starts a campaign. If in `draft`, transitions through `scheduled` → `running` automatically. Requires a non-empty phone list.
+
+**Roles:** `admin`, `manager`
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Phone list is empty |
+| 400 | Invalid transition (e.g., already completed) |
+| 404 | Campaign not found |
+
+#### POST /campaigns/:id/pause
+
+Pauses a running campaign.
+
+**Roles:** `admin`, `manager`
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Campaign is not running |
+
+#### POST /campaigns/:id/resume
+
+Resumes a paused campaign.
+
+**Roles:** `admin`, `manager`
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Campaign is not paused |
+
+#### POST /campaigns/:id/stop
+
+Permanently stops a campaign (marks as completed). Works from any non-completed status.
+
+**Roles:** `admin`, `manager`
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Campaign is already completed |
+
+---
+
+### POST /campaigns/:id/phone-list
+
+Uploads a phone number list. Only allowed in `draft` or `scheduled` status. Replaces the existing list.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`
+
+**Request Body (JSON array):**
+
+```json
+{
+  "numbers": ["+905551234567", "+905559876543", "+905551112233"]
+}
+```
+
+**Request Body (CSV string):**
+
+```json
+{
+  "csv": "phone\n+905551234567\n+905559876543\n+905551112233"
+}
+```
+
+The CSV parser:
+- Takes the first column from each row
+- Skips header rows (phone, number, tel, numara)
+- Strips non-digit characters, requires 10+ digits
+- Adds `+` prefix if missing
+- Deduplicates
+
+**200 OK:**
+
+```json
+{
+  "campaign": {
+    "id": "664f1e...",
+    "phone_count": 3,
+    "stats": {
+      "total": 3,
+      "pending": 3,
+      "completed": 0,
+      "failed": 0,
+      "no_answer": 0,
+      "voicemail": 0
+    }
+  }
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 400 | Neither `numbers` nor `csv` provided |
+| 400 | No valid phone numbers found |
+| 400 | Campaign is not in draft or scheduled status |
+| 404 | Campaign not found |
+
+---
+
+### GET /campaigns/:id/results
+
+Returns structured survey results for all calls in the campaign, plus aggregated stats from actual Call records.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`, `viewer`
+
+**200 OK:**
+
+```json
+{
+  "campaign": {
+    "id": "664f1e...",
+    "name": "Ocak Anketi",
+    "status": "running",
+    "stats": { "total": 100, "pending": 50, "completed": 42, "..." : "..." },
+    "call_stats": { "total": 45, "completed": 42, "failed": 2, "no_answer": 1 }
+  },
+  "results": [
+    {
+      "call_id": "664f1f...",
+      "caller_number": "+905551234567",
+      "status": "completed",
+      "duration_seconds": 180,
+      "survey_responses": [
+        {
+          "question_id": "Q1",
+          "question_text": "Hizmetimizi nasil degerlendirirsiniz?",
+          "answer": "4",
+          "parsed_value": 4
+        }
+      ],
+      "llm_summary": null,
+      "createdAt": "2025-01-15T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Campaign not found |
+
+---
+
+### GET /campaigns/:id/results/export
+
+Downloads campaign results as a CSV file. Columns include phone number, status, duration, date, one column per survey question, and summary.
+
+**Auth:** Bearer token
+**Feature:** `outbound_campaigns`
+**Roles:** `admin`, `manager`, `viewer`
+
+**Response:**
+
+- `Content-Type: text/csv; charset=utf-8`
+- `Content-Disposition: attachment; filename="campaign-{id}-results.csv"`
+
+**Example CSV:**
+
+```
+Telefon,Durum,Sure (sn),Tarih,Hizmetimizi nasil degerlendirirsiniz?,Tekrar tercih eder misiniz?,Ozet
++905551234567,completed,180,2025-01-15T10:00:00.000Z,4,Evet,
++905559876543,completed,120,2025-01-15T11:00:00.000Z,5,Evet,
++905551112233,no_answer,0,2025-01-15T12:00:00.000Z,,,
+```
+
+**Errors:**
+
+| Status | Condition |
+|--------|-----------|
+| 404 | Campaign not found |
+
+---
+
+## Billing
+
+Base URL: `/billing`
+
+All routes require authentication. Admin only.
+
+### GET /billing/usage
+
+Returns usage summary for the current billing period (calendar month). Aggregates call counts, durations, and charges from actual Call and BillingEvent records.
+
+**Auth:** Bearer token
+**Roles:** `admin`
+
+**200 OK:**
+
+```json
+{
+  "usage": {
+    "period_start": "2025-02-01T00:00:00.000Z",
+    "period_end": "2025-02-28T23:59:59.999Z",
+    "total_calls": 150,
+    "total_duration_seconds": 14325,
+    "total_duration_minutes": 239,
+    "inbound_calls": 100,
+    "outbound_calls": 50,
+    "total_charges": 358.5,
+    "currency": "TRY"
+  }
+}
+```
+
+**Pricing:** Calls are charged at **1.5 TRY per minute** (rounded up to nearest minute). A billing event is automatically logged after each completed call via the webhook pipeline.
+
+---
+
+### GET /billing/history
+
+Returns paginated billing event history. Each event includes type, amount, and linked call details.
+
+**Auth:** Bearer token
+**Roles:** `admin`
+
+**Query Parameters:**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `page` | number | `1` | Page number |
+| `type` | string | - | Filter: `call_charge`, `subscription`, `top_up`, `refund` |
+
+**200 OK:**
+
+```json
+{
+  "events": [
+    {
+      "_id": "664f20...",
+      "tenant_id": "664f1a...",
+      "type": "call_charge",
+      "amount": 3,
+      "currency": "TRY",
+      "call_id": {
+        "_id": "664f1f...",
+        "caller_number": "+905551234567",
+        "duration_seconds": 120,
+        "direction": "inbound"
+      },
+      "param_transaction_id": null,
+      "description": "Arama ucreti: 2 dk",
+      "createdAt": "2025-02-15T10:00:00.000Z"
+    }
+  ],
+  "total": 150,
+  "page": 1,
+  "totalPages": 8
+}
+```
+
+**Billing event types:**
+
+| Type | Description |
+|------|-------------|
+| `call_charge` | Auto-logged per completed call |
+| `subscription` | Monthly subscription charge (future) |
+| `top_up` | Balance top-up via payment (future) |
+| `refund` | Refund (future) |
+
+---
+
+## Route Summary
+
+| Method | Path | Auth | Feature | Roles | Description |
+|--------|------|------|---------|-------|-------------|
+| GET | `/tenants/me` | JWT | - | any | Get tenant details |
+| PUT | `/tenants/me` | JWT | - | admin | Update tenant settings |
+| GET | `/users` | JWT | - | all | List tenant users |
+| POST | `/users/invite` | JWT | - | admin | Create user |
+| PUT | `/users/:id` | JWT | - | admin | Update user role/name |
+| DELETE | `/users/:id` | JWT | - | admin | Remove user |
+| GET | `/calls` | JWT | - | all | List calls (paginated) |
+| GET | `/calls/stats` | JWT | - | all | Call statistics |
+| GET | `/calls/:id` | JWT | - | all | Call detail |
+| GET | `/surveys` | JWT | survey_builder | all | List surveys |
+| POST | `/surveys` | JWT | survey_builder | admin, manager | Create survey |
+| GET | `/surveys/:id` | JWT | survey_builder | all | Survey detail |
+| PUT | `/surveys/:id` | JWT | survey_builder | admin, manager | Update survey |
+| DELETE | `/surveys/:id` | JWT | survey_builder | admin, manager | Delete survey |
+| POST | `/surveys/:id/duplicate` | JWT | survey_builder | admin, manager | Clone survey |
+| GET | `/campaigns` | JWT | outbound_campaigns | all | List campaigns |
+| POST | `/campaigns` | JWT | outbound_campaigns | admin, manager | Create campaign |
+| GET | `/campaigns/:id` | JWT | outbound_campaigns | all | Campaign detail |
+| PUT | `/campaigns/:id` | JWT | outbound_campaigns | admin, manager | Update campaign |
+| POST | `/campaigns/:id/start` | JWT | outbound_campaigns | admin, manager | Start campaign |
+| POST | `/campaigns/:id/pause` | JWT | outbound_campaigns | admin, manager | Pause campaign |
+| POST | `/campaigns/:id/resume` | JWT | outbound_campaigns | admin, manager | Resume campaign |
+| POST | `/campaigns/:id/stop` | JWT | outbound_campaigns | admin, manager | Stop campaign |
+| POST | `/campaigns/:id/phone-list` | JWT | outbound_campaigns | admin, manager | Upload phone list |
+| GET | `/campaigns/:id/results` | JWT | outbound_campaigns | all | Survey results |
+| GET | `/campaigns/:id/results/export` | JWT | outbound_campaigns | all | Export CSV |
+| GET | `/billing/usage` | JWT | - | admin | Current period usage |
+| GET | `/billing/history` | JWT | - | admin | Billing event history |
+| POST | `/webhooks/elevenlabs` | HMAC | - | - | ElevenLabs webhook |