elevenlabs-webhook-nodejs 1.0.0

package/docs/ELEVENLABS_WEBHOOK_TOOLS.md

@@ -0,0 +1,644 @@
+# ElevenLabs Webhook Tools — Setup Guide
+
+> Webhook tools allow the AI agent to call your backend during **SIP trunk voice calls** (inbound & outbound). Unlike client tools (used for WhatsApp text conversations over WebSocket), webhook tools are HTTP endpoints that ElevenLabs POSTs to during a live call.
+
+---
+
+## Table of Contents
+
+1. [Overview](#1-overview)
+2. [Architecture](#2-architecture)
+3. [Prerequisites](#3-prerequisites)
+4. [Creating Webhook Tools in ElevenLabs Panel](#4-creating-webhook-tools-in-elevenlabs-panel)
+5. [Tool Reference](#5-tool-reference)
+6. [Dynamic Variables Setup](#6-dynamic-variables-setup)
+7. [Testing](#7-testing)
+8. [Troubleshooting](#8-troubleshooting)
+
+---
+
+## 1. Overview
+
+During a SIP trunk voice call, the AI agent can invoke **webhook tools** to perform actions like checking appointment availability, booking slots, or retrieving patient history. ElevenLabs sends an HTTP POST to your server, waits for the JSON response, and uses it to continue the conversation.
+
+**Available webhook tools:**
+
+| Tool | Purpose |
+|------|---------|
+| `check_availability` | Check available appointment slots for a given date |
+| `reserve_slot` | Book an appointment on Google Calendar |
+| `list_reservations` | List the patient's upcoming appointments |
+| `cancel_reservation` | Cancel an existing appointment |
+| `reschedule_reservation` | Cancel an old appointment and book a new one |
+| `check_patient_history` | Retrieve patient profile, past appointments, and interaction history |
+
+---
+
+## 2. Architecture
+
+```
+┌──────────────┐         POST /webhooks/elevenlabs/tools/:toolName
+│  ElevenLabs  │ ──────────────────────────────────────────────────► ┌──────────────┐
+│  AI Agent    │                                                     │  Our Backend │
+│  (SIP Call)  │ ◄────────────────────────────────────────────────── │  (Fastify)   │
+└──────────────┘         JSON response (tool result)                 └──────┬───────┘
+                                                                           │
+                                                                    ┌──────▼───────┐
+                                                                    │ Google Cal / │
+                                                                    │ MongoDB / SMS│
+                                                                    └──────────────┘
+```
+
+**Flow:**
+1. Patient calls the clinic's SIP number (inbound) or AI calls the patient (outbound)
+2. During the conversation, the AI decides to use a tool (e.g., "Let me check availability for Monday")
+3. ElevenLabs POSTs to the configured webhook URL with the tool parameters
+4. Our backend resolves the tenant from `agent_id`, executes the tool logic, returns JSON
+5. ElevenLabs reads the response and the AI continues the conversation naturally
+
+---
+
+## 3. Prerequisites
+
+Before configuring webhook tools, ensure:
+
+- [ ] Your backend is deployed and publicly accessible (HTTPS required)
+- [ ] `ELEVENLABS_WEBHOOK_SECRET` is set in your `.env` file
+- [ ] The tenant has **Google Calendar connected** (for appointment tools)
+- [ ] The ElevenLabs agent exists in the `agents` collection with a valid `elevenlabs_agent_id`
+- [ ] The agent is assigned to a tenant and is `is_active: true`
+
+---
+
+## 4. Creating Webhook Tools in ElevenLabs Panel
+
+### Step-by-Step for Each Tool
+
+1. Go to [ElevenLabs Dashboard](https://elevenlabs.io/app/conversational-ai)
+2. Select your **voice agent** (the one used for SIP trunk calls)
+3. Navigate to the **Tools** section in the agent configuration
+4. Click **"Add Tool"** → Select **"Webhook"**
+
+For each tool below, fill in the fields as described.
+
+---
+
+### 4.1. check_availability
+
+**Purpose:** Check available appointment slots for a specific date.
+
+| Field | Value |
+|-------|-------|
+| **Name** | `check_availability` |
+| **Description** | `Belirtilen tarih için müsait randevu saatlerini kontrol eder. Hasta randevu almak istediğinde önce bu aracı kullanarak müsait saatleri kontrol et.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/check_availability` |
+| **Method** | `POST` |
+
+**Request Headers:**
+
+| Key | Value |
+|-----|-------|
+| `x-api-key` | `{your ELEVENLABS_WEBHOOK_SECRET}` |
+| `Content-Type` | `application/json` |
+
+**Request Body Schema (Properties):**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | `Sistem tarafından otomatik sağlanır. Değer: {{agent_id}}` |
+| `conversation_id` | `string` | No | `Sistem tarafından otomatik sağlanır. Değer: {{conversation_id}}` |
+| `patient_phone` | `string` | Yes | `Sistem tarafından otomatik sağlanır. Değer: {{phone_number}}` |
+| `patient_name` | `string` | No | `Hastanın adı (varsa). Değer: {{patient_name}}` |
+| `date` | `string` | Yes | `Kontrol edilecek tarih. YYYY-MM-DD formatında (ör: 2026-03-15)` |
+
+> **Important:** Mark `agent_id`, `conversation_id`, `patient_phone`, `patient_name` as **hidden/fixed** parameters with their dynamic variable values. Only `date` should be filled by the AI.
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `10` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` (while checking) |
+| **Pre-tool speech** | `true` — Set speech like: `"Bir saniye, o tarihe bakıyorum..."` |
+
+---
+
+### 4.2. reserve_slot
+
+**Purpose:** Book an appointment slot.
+
+| Field | Value |
+|-------|-------|
+| **Name** | `reserve_slot` |
+| **Description** | `Hastaya randevu oluşturur. Önce check_availability ile müsait saatleri kontrol et, sonra hastanın seçtiği saati bu araçla rezerve et.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/reserve_slot` |
+| **Method** | `POST` |
+
+**Request Headers:** (Same as check_availability)
+
+**Request Body Schema:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | Hidden. `{{agent_id}}` |
+| `conversation_id` | `string` | No | Hidden. `{{conversation_id}}` |
+| `patient_phone` | `string` | Yes | Hidden. `{{phone_number}}` |
+| `patient_name` | `string` | Yes | `Hastanın adı soyadı` |
+| `iso_start` | `string` | Yes | `Randevu başlangıç zamanı ISO 8601 formatında (ör: 2026-03-15T10:00:00+03:00)` |
+| `iso_end` | `string` | Yes | `Randevu bitiş zamanı ISO 8601 formatında (ör: 2026-03-15T10:30:00+03:00)` |
+| `notes` | `string` | No | `Randevu notu (hastanın belirttiği şikayet, istek vb.)` |
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `15` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` |
+| **Pre-tool speech** | `true` — `"Randevunuzu oluşturuyorum, bir saniye lütfen..."` |
+
+---
+
+### 4.3. list_reservations
+
+**Purpose:** List patient's upcoming appointments.
+
+| Field | Value |
+|-------|-------|
+| **Name** | `list_reservations` |
+| **Description** | `Hastanın mevcut randevularını listeler. Hasta mevcut randevularını sormak istediğinde bu aracı kullan.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/list_reservations` |
+| **Method** | `POST` |
+
+**Request Headers:** (Same)
+
+**Request Body Schema:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | Hidden. `{{agent_id}}` |
+| `conversation_id` | `string` | No | Hidden. `{{conversation_id}}` |
+| `patient_phone` | `string` | Yes | Hidden. `{{phone_number}}` |
+| `patient_name` | `string` | No | Hidden. `{{patient_name}}` |
+
+> No additional AI-filled parameters needed. All context comes from dynamic variables.
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `10` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` |
+| **Pre-tool speech** | `true` — `"Randevularınıza bakıyorum..."` |
+
+---
+
+### 4.4. cancel_reservation
+
+**Purpose:** Cancel an existing appointment.
+
+| Field | Value |
+|-------|-------|
+| **Name** | `cancel_reservation` |
+| **Description** | `Hastanın mevcut bir randevusunu iptal eder. Önce list_reservations ile randevuları listele, sonra hastanın iptal etmek istediği randevunun event_id değerini bu araçla gönder.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/cancel_reservation` |
+| **Method** | `POST` |
+
+**Request Headers:** (Same)
+
+**Request Body Schema:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | Hidden. `{{agent_id}}` |
+| `conversation_id` | `string` | No | Hidden. `{{conversation_id}}` |
+| `patient_phone` | `string` | Yes | Hidden. `{{phone_number}}` |
+| `patient_name` | `string` | No | Hidden. `{{patient_name}}` |
+| `event_id` | `string` | Yes | `İptal edilecek randevunun event_id değeri (list_reservations sonucundan alınır)` |
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `10` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` |
+| **Pre-tool speech** | `true` — `"Randevunuzu iptal ediyorum..."` |
+
+---
+
+### 4.5. reschedule_reservation
+
+**Purpose:** Reschedule (cancel old + book new) in one step.
+
+| Field | Value |
+|-------|-------|
+| **Name** | `reschedule_reservation` |
+| **Description** | `Hastanın mevcut randevusunu başka bir tarihe/saate taşır. Eski randevuyu iptal edip yeni randevuyu oluşturur. Önce list_reservations ile mevcut randevuyu bul, sonra check_availability ile yeni tarihteki müsait saatleri kontrol et.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/reschedule_reservation` |
+| **Method** | `POST` |
+
+**Request Headers:** (Same)
+
+**Request Body Schema:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | Hidden. `{{agent_id}}` |
+| `conversation_id` | `string` | No | Hidden. `{{conversation_id}}` |
+| `patient_phone` | `string` | Yes | Hidden. `{{phone_number}}` |
+| `patient_name` | `string` | Yes | `Hastanın adı soyadı` |
+| `old_event_id` | `string` | Yes | `Eski randevunun event_id değeri` |
+| `new_iso_start` | `string` | Yes | `Yeni randevu başlangıç zamanı ISO 8601 formatında` |
+| `new_iso_end` | `string` | Yes | `Yeni randevu bitiş zamanı ISO 8601 formatında` |
+| `notes` | `string` | No | `Randevu notu` |
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `20` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` |
+| **Pre-tool speech** | `true` — `"Randevunuzu yeni tarihe taşıyorum, bir saniye..."` |
+
+---
+
+### 4.6. check_patient_history
+
+**Purpose:** Retrieve full patient history for context during the call.
+
+| Field | Value |
+|-------|-------|
+| **Name** | `check_patient_history` |
+| **Description** | `Hastanın geçmiş randevularını, iletişim profilini ve önceki etkileşimlerini getirir. Hasta hakkında bilgi edinmek veya geçmiş randevularını sorgulamak için kullan.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/check_patient_history` |
+| **Method** | `POST` |
+
+**Request Headers:** (Same)
+
+**Request Body Schema:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | Hidden. `{{agent_id}}` |
+| `conversation_id` | `string` | No | Hidden. `{{conversation_id}}` |
+| `patient_phone` | `string` | Yes | Hidden. `{{phone_number}}` |
+| `patient_name` | `string` | No | Hidden. `{{patient_name}}` |
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `10` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` |
+| **Pre-tool speech** | `true` — `"Bilgilerinize bakıyorum..."` |
+
+---
+
+## 5. Tool Reference
+
+### Request Format
+
+All tools receive a POST request with JSON body. The body contains both **context fields** (injected via dynamic variables) and **tool-specific parameters** (filled by the AI).
+
+```json
+{
+  "agent_id": "agent_xxxxxxxxxxxx",
+  "conversation_id": "conv_xxxxxxxxxxxx",
+  "patient_phone": "+905551234567",
+  "patient_name": "Ahmet Yilmaz",
+  "date": "2026-03-15"
+}
+```
+
+### Response Format
+
+All tools return JSON. Success responses return `200`, errors return `422`.
+
+**Success example (check_availability):**
+```json
+{
+  "date": "2026-03-15",
+  "available_slots": [
+    { "start": "09:00", "end": "09:30" },
+    { "start": "10:00", "end": "10:30" },
+    { "start": "14:00", "end": "14:30" }
+  ],
+  "appointment_duration_minutes": 30
+}
+```
+
+**Success example (reserve_slot):**
+```json
+{
+  "reserved": true,
+  "event_id": "abc123xyz",
+  "start": "2026-03-15T10:00:00+03:00",
+  "end": "2026-03-15T10:30:00+03:00",
+  "patient_name": "Ahmet Yilmaz"
+}
+```
+
+**Success example (list_reservations):**
+```json
+{
+  "reservations": [
+    {
+      "event_id": "abc123xyz",
+      "summary": "Ahmet Yilmaz - Randevu",
+      "start": "2026-03-15T10:00:00+03:00",
+      "end": "2026-03-15T10:30:00+03:00"
+    }
+  ],
+  "count": 1
+}
+```
+
+**Success example (cancel_reservation):**
+```json
+{
+  "cancelled": true,
+  "event_id": "abc123xyz"
+}
+```
+
+**Success example (reschedule_reservation):**
+```json
+{
+  "rescheduled": true,
+  "old_event_id": "abc123xyz",
+  "new_event_id": "def456uvw",
+  "start": "2026-03-16T14:00:00+03:00",
+  "end": "2026-03-16T14:30:00+03:00",
+  "patient_name": "Ahmet Yilmaz"
+}
+```
+
+**Error example:**
+```json
+{
+  "error": "Google Calendar not configured"
+}
+```
+
+---
+
+## 6. Dynamic Variables Setup
+
+Dynamic variables are injected at conversation start and are available to all webhook tools. Configure these on the agent's **Dynamic Variables** section.
+
+### For Outbound Calls (call_patient)
+
+These are automatically injected by our backend when initiating a SIP trunk outbound call via `toolCallPatient`:
+
+| Variable | Source | Example |
+|----------|--------|---------|
+| `patient_name` | WhatsApp chat contact name | `Ahmet Yilmaz` |
+| `patient_phone` | WhatsApp chat contact phone | `+905551234567` |
+| `conversation_history` | Built from chat context | `Patient: Merhaba...` |
+| `call_reason` | AI-provided reason for calling | `Randevu hatırlatması` |
+
+### For Inbound Calls (SIP Trunk)
+
+Configure these dynamic variables in the ElevenLabs agent settings:
+
+| Variable | Value / Source | Description |
+|----------|---------------|-------------|
+| `agent_id` | The agent's own ID (hardcode it) | Used to resolve tenant in webhook |
+| `phone_number` | `{{phone_number}}` (ElevenLabs built-in) | Caller's phone number from SIP |
+| `patient_name` | `{{caller_name}}` or empty | Caller ID name if available |
+| `current_date` | `{{current_date}}` or hardcode | Today's date for the AI |
+
+> **Note:** `{{phone_number}}` is an ElevenLabs built-in variable for SIP/phone calls that resolves to the caller's phone number in E.164 format.
+
+### Mapping Dynamic Variables to Tool Parameters
+
+In the webhook tool schema, reference dynamic variables using `{{variable_name}}` syntax for hidden/fixed parameters:
+
+```
+agent_id       → {{agent_id}}
+patient_phone  → {{phone_number}}
+patient_name   → {{patient_name}}
+conversation_id → {{conversation_id}}
+```
+
+This way, these values are automatically injected into every tool call without the AI needing to fill them.
+
+---
+
+## 7. Testing
+
+### cURL Test
+
+Test the webhook endpoint directly:
+
+```bash
+# check_availability
+curl -X POST https://YOUR_DOMAIN/webhooks/elevenlabs/tools/check_availability \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_ELEVENLABS_WEBHOOK_SECRET" \
+  -d '{
+    "agent_id": "agent_xxxxxxxxxxxx",
+    "conversation_id": "test_conv_001",
+    "patient_phone": "+905551234567",
+    "patient_name": "Test Hasta",
+    "date": "2026-03-15"
+  }'
+
+# reserve_slot
+curl -X POST https://YOUR_DOMAIN/webhooks/elevenlabs/tools/reserve_slot \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_ELEVENLABS_WEBHOOK_SECRET" \
+  -d '{
+    "agent_id": "agent_xxxxxxxxxxxx",
+    "conversation_id": "test_conv_001",
+    "patient_phone": "+905551234567",
+    "patient_name": "Test Hasta",
+    "iso_start": "2026-03-15T10:00:00+03:00",
+    "iso_end": "2026-03-15T10:30:00+03:00",
+    "notes": "Dis agrisi"
+  }'
+
+# list_reservations
+curl -X POST https://YOUR_DOMAIN/webhooks/elevenlabs/tools/list_reservations \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_ELEVENLABS_WEBHOOK_SECRET" \
+  -d '{
+    "agent_id": "agent_xxxxxxxxxxxx",
+    "patient_phone": "+905551234567"
+  }'
+
+# cancel_reservation
+curl -X POST https://YOUR_DOMAIN/webhooks/elevenlabs/tools/cancel_reservation \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_ELEVENLABS_WEBHOOK_SECRET" \
+  -d '{
+    "agent_id": "agent_xxxxxxxxxxxx",
+    "patient_phone": "+905551234567",
+    "event_id": "abc123xyz"
+  }'
+
+# check_patient_history
+curl -X POST https://YOUR_DOMAIN/webhooks/elevenlabs/tools/check_patient_history \
+  -H "Content-Type: application/json" \
+  -H "x-api-key: YOUR_ELEVENLABS_WEBHOOK_SECRET" \
+  -d '{
+    "agent_id": "agent_xxxxxxxxxxxx",
+    "patient_phone": "+905551234567"
+  }'
+```
+
+### Checklist
+
+- [ ] Backend returns `200` with correct JSON for each tool
+- [ ] Backend returns `401` when `x-api-key` is missing or wrong
+- [ ] Backend returns `404` for unknown tool names
+- [ ] Backend returns `400` when `agent_id` is missing
+- [ ] Backend returns `422` with `{ "error": "..." }` for business logic errors
+- [ ] Appointments created via voice call have `source: "voice_call"` in MongoDB
+- [ ] SMS notifications fire when appointment is created/cancelled/rescheduled
+- [ ] Test an actual SIP call end-to-end and verify the AI uses tools correctly
+
+---
+
+## 8. Troubleshooting
+
+### Common Issues
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `401 Unauthorized` | Wrong `x-api-key` header | Ensure the header value matches `ELEVENLABS_WEBHOOK_SECRET` in `.env` |
+| `400 agent_id is required` | Dynamic variable not mapped | Add `agent_id` as a hidden parameter with `{{agent_id}}` value |
+| `Agent not found or inactive` | `elevenlabs_agent_id` doesn't match any active agent | Verify the agent exists in the `agents` collection and `is_active: true` |
+| `Google Calendar not configured` | Tenant hasn't connected Google Calendar | Connect Google Calendar in tenant settings |
+| Tool timeout (no response) | Backend unreachable or slow | Check server logs; increase `response_timeout_secs` in tool config |
+| AI doesn't use the tool | Tool description unclear | Improve the tool description in ElevenLabs to better guide the AI |
+
+### Logs
+
+All webhook tool calls are logged with:
+```
+Webhook tool call received  { toolName, agentId, conversationId, patientPhone }
+Webhook tool call completed { toolName, agentId, conversationId, resultPreview }
+```
+
+Check server logs for `Webhook tool call` entries.
+
+---
+
+## 9. Appointment Validation Agent Setup
+
+The appointment validation system uses batch outbound calls to confirm patient appointments. A dedicated ElevenLabs agent handles these calls with a specific webhook tool.
+
+### Agent Prompt (Turkish)
+
+```
+Sen {{clinic_name}} kliniginin randevu onay asistanisin. Hastaneden ariyorsun ve hastanin randevusunu onaylamak istiyorsun.
+
+Gorev:
+1. Kendinizi tanit: "Merhaba, ben {{clinic_name}}'den ariyorum"
+2. Hastanin adini dogrula: "{{patient_name}} ile mi gorusuyorum?"
+3. Randevu bilgilerini oku: "{{appointment_date}} tarihinde saat {{appointment_time}}'de {{doctor_name}} ile randevunuz bulunuyor"
+4. Hastaya randevuyu onaylayip onaylamadığını sor
+5. Hasta onaylarsa "confirm_appointment_validation" aracini result="confirmed" ile cagir
+6. Hasta iptal etmek isterse "confirm_appointment_validation" aracini result="cancelled" ile cagir
+7. Hasta ertelemek isterse yeni tercih edilen zamani sor ve "confirm_appointment_validation" aracini result="reschedule" ile cagir, reschedule_request alanina hastanin tercihini yaz
+8. Kibarca vedalas
+
+Onemli kurallar:
+- Kisa ve net konus
+- Hasta telefona cevap vermezse veya mesgulse araci cagirma
+- Her durumda "confirm_appointment_validation" aracini tam olarak bir kez cagir
+- Hastanin mesajini patient_message alanina kisa ozetle
+```
+
+### Dynamic Variables
+
+Configure these on the agent:
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `clinic_name` | Per-recipient (from tenant) | Clinic/tenant name — auto-injected |
+| `patient_name` | Per-recipient | Patient's full name |
+| `patient_phone` | Per-recipient | Patient phone (E.164) |
+| `appointment_date` | Per-recipient | Appointment date (YYYY-MM-DD) |
+| `appointment_time` | Per-recipient | Appointment time (HH:MM) |
+| `doctor_name` | Per-recipient | Doctor name |
+| `department` | Per-recipient | Department |
+| `notes` | Per-recipient | Additional notes |
+| `current_date` | Per-recipient | Today's date |
+
+These are injected automatically via `conversationInitiationClientData.dynamicVariables` for each recipient in the batch call.
+
+### Webhook Tool: `confirm_appointment_validation`
+
+| Field | Value |
+|-------|-------|
+| **Name** | `confirm_appointment_validation` |
+| **Description** | `Hastanin randevu onay sonucunu kaydeder. Hasta randevuyu onaylarsa, iptal ederse veya ertelemek isterse bu araci cagir.` |
+| **Webhook URL** | `https://YOUR_DOMAIN/webhooks/elevenlabs/tools/confirm_appointment_validation` |
+| **Method** | `POST` |
+
+**Request Headers:**
+
+| Key | Value |
+|-----|-------|
+| `x-api-key` | `{your ELEVENLABS_WEBHOOK_SECRET}` |
+| `Content-Type` | `application/json` |
+
+**Request Body Schema:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `agent_id` | `string` | Yes | Hidden. `{{agent_id}}` |
+| `conversation_id` | `string` | Yes | Hidden. `{{conversation_id}}` |
+| `patient_phone` | `string` | Yes | Hidden. `{{phone_number}}` |
+| `result` | `string` | Yes | `Sonuc: "confirmed", "cancelled", veya "reschedule"` |
+| `reschedule_request` | `string` | No | `Hastanin tercih ettigi yeni zaman (erteleme durumunda)` |
+| `patient_message` | `string` | No | `Hastanin iletmek istedigi mesaj veya not` |
+
+**Tool Settings:**
+
+| Setting | Value |
+|---------|-------|
+| **Response timeout** | `10` seconds |
+| **Execution mode** | `immediate` |
+| **Disable interruptions** | `true` |
+| **Pre-tool speech** | `false` |
+
+### Response Examples
+
+**Success:**
+```json
+{
+  "recorded": true,
+  "result": "confirmed"
+}
+```
+
+**Error (conversation not found):**
+```json
+{
+  "error": "Appointment not found for this conversation"
+}
+```
+
+---
+
+## File Map
+
+| File | Purpose |
+|------|---------|
+| `src/modules/webhooks/elevenlabs-tool.routes.ts` | Fastify route — auth + dispatch |
+| `src/modules/webhooks/elevenlabs-tool.service.ts` | Tool handler logic — tenant resolution + tool implementations |
+| `src/modules/whatsapp/appointment.model.ts` | Appointment model — supports `source: 'voice_call'` |
+| `src/modules/appointment-validation/appointment-validation.model.ts` | Batch model — tracks validation campaigns and entries |
+| `src/modules/appointment-validation/appointment-validation.service.ts` | Batch business logic — create, submit, sync, export |
+| `src/modules/appointment-validation/appointment-validation.routes.ts` | Batch REST endpoints |
+| `src/services/google-calendar.service.ts` | Google Calendar API — shared by both client and webhook tools |
+| `src/services/elevenlabs.service.ts` | ElevenLabs SDK wrapper — SIP trunk + batch calling |
+| `src/app.ts` | Route registration — `/webhooks/elevenlabs/tools` + `/appointment-validation` |