elevenlabs-webhook-nodejs 1.0.0

package/docs/CLIENT_TOOLS_AND_FEATURES.md

@@ -0,0 +1,337 @@
+# Client Tools & Feature Flags
+
+## Feature Flags
+
+Feature flags are stored in `tenant.enabled_features[]` and toggled via the superadmin panel.
+
+| Flag | Description |
+|---|---|
+| `whatsapp_agent` | Core WhatsApp AI agent |
+| `google_calendar` | Google Calendar integration for appointment booking |
+| `operator_workflow` | Photo forwarding to doctor (operator) |
+| `conversation_forwarding` | Text/conversation forwarding to doctor or assistant |
+| `chat_continuity` | Preserve conversation context across WS reconnections |
+| `sms_notifications` | SMS notifications via NetGSM |
+| `appointment_validation` | Batch outbound calls for appointment confirmation |
+| `inbound_call_schedule` | Schedule-based inbound call agent assignment |
+| `voice_transcription` | Voice message transcription (STT) |
+
+---
+
+## Client Tools (ElevenLabs WebSocket)
+
+These tools are called by the ElevenLabs AI during a WhatsApp conversation. They must be registered on the ElevenLabs agent dashboard.
+
+### `forward_to_operator`
+
+Forwards patient's photos/media to the doctor for review.
+
+**Requires:** `operator_workflow` feature flag, `operator_phone` configured
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `message` | string (optional) | Note/context for the doctor |
+
+**Behavior:**
+- Finds all media messages (image/video/document) from the patient in the current session
+- Forwards each to `operator_phone` with REF code caption
+- Creates `OperatorRequest` with `request_type: 'operator_review'`
+- Sets `session.awaiting_operator = true`
+
+**Returns:** `{ ref_code, forwarded, total_media, forwarded_ok, failed }`
+
+**ElevenLabs Tool Config:**
+```
+Name: forward_to_operator
+Type: Client
+Description: Hastanın fotoğraflarını/medyasını değerlendirme için doktora iletir. Hasta fotoğraf gönderdiğinde ve doktor değerlendirmesi gerektiğinde kullan.
+Parameters:
+  - message (string, optional): Doktora iletilecek not veya bağlam
+Wait for response: true
+```
+
+---
+
+### `forward_conversation_to_operator`
+
+Forwards a summary and selected patient messages to a configured phone number. Used when the patient's request needs human input (pricing, discounts, custom questions).
+
+**Requires:** `conversation_forwarding` feature flag, `conversation_forwarding_phone` configured
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `summary` | string | AI's summary of the patient's request |
+| `patient_messages` | string[] | Specific patient messages to forward |
+
+**Behavior:**
+- Sends formatted text to `conversation_forwarding_phone`: REF + patient info + summary + messages
+- Creates `OperatorRequest` with `request_type: 'conversation_review'`
+- Sets `session.awaiting_operator = true`
+- Uses the same session REF code as other forwards
+
+**Returns:** `{ ref_code, forwarded, message_count }`
+
+**ElevenLabs Tool Config:**
+```
+Name: forward_conversation_to_operator
+Type: Client
+Description: Hastanın metin mesajlarını ve talebinin özetini doktora/asistana iletir. Fiyat, indirim, özel talep gibi doktor kararı gereken durumlarda kullan.
+Parameters:
+  - summary (string, required): Hastanın talebinin kısa özeti
+  - patient_messages (array of string, required): İletilecek hasta mesajları listesi
+Wait for response: true
+```
+
+---
+
+### `send_example_photo`
+
+Sends a pre-configured guide photo to the patient (e.g., camera angle, posing instructions).
+
+**Requires:** `operator_example_photo_enabled`, `operator_example_photo_base64` configured
+
+**Parameters:** None
+
+**Returns:** `{ sent: true/false }`
+
+**ElevenLabs Tool Config:**
+```
+Name: send_example_photo
+Type: Client
+Description: Hastaya rehber fotoğraf gönderir (çekim açısı, poz talimatları). Hasta nasıl fotoğraf çekeceğini bilmediğinde kullan.
+Parameters: (none)
+Wait for response: true
+```
+
+---
+
+### `call_patient`
+
+Initiates an outbound voice call to the patient via ElevenLabs SIP trunk.
+
+**Requires:** `outbound_call_enabled`, `outbound_call_phone_number_id` configured
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `reason` | string (optional) | Reason for the call, passed to voice agent |
+
+**Returns:** `{ success, conversation_id }` or `{ success: false, reason }` on SIP failure
+
+**ElevenLabs Tool Config:**
+```
+Name: call_patient
+Type: Client
+Description: Hastayı telefonla arar. Hasta telefonda görüşmek istediğinde veya acil bilgilendirme gerektiğinde kullan.
+Parameters:
+  - reason (string, optional): Arama nedeni
+Wait for response: true
+```
+
+---
+
+### `check_availability`
+
+Checks available appointment slots for a given date.
+
+**Requires:** `google_calendar` feature flag, Google Calendar connected
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `date` | string | Date in YYYY-MM-DD format |
+
+**Returns:** `{ date, available_slots, appointment_duration_minutes }`
+
+**ElevenLabs Tool Config:**
+```
+Name: check_availability
+Type: Client
+Description: Belirtilen tarih için müsait randevu saatlerini kontrol eder.
+Parameters:
+  - date (string, required): Tarih, YYYY-MM-DD formatında
+Wait for response: true
+```
+
+---
+
+### `reserve_slot`
+
+Books an appointment slot on Google Calendar.
+
+**Requires:** `google_calendar` feature flag, Google Calendar connected
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `iso_start` | string | Start time in ISO format |
+| `iso_end` | string | End time in ISO format |
+| `patient_name` | string (optional) | Falls back to contact name |
+| `notes` | string (optional) | Appointment notes |
+
+**Returns:** `{ reserved, event_id, start, end, patient_name }`
+
+**ElevenLabs Tool Config:**
+```
+Name: reserve_slot
+Type: Client
+Description: Randevu oluşturur. Hasta tarih ve saat onayladıktan sonra kullan.
+Parameters:
+  - iso_start (string, required): Başlangıç zamanı, ISO 8601 formatında
+  - iso_end (string, required): Bitiş zamanı, ISO 8601 formatında
+  - patient_name (string, optional): Hasta adı
+  - notes (string, optional): Randevu notu
+Wait for response: true
+```
+
+---
+
+### `list_reservations`
+
+Lists the patient's upcoming reservations on Google Calendar.
+
+**Requires:** `google_calendar` feature flag
+
+**Parameters:** None (patient identified by phone number)
+
+**Returns:** `{ reservations, count }`
+
+**ElevenLabs Tool Config:**
+```
+Name: list_reservations
+Type: Client
+Description: Hastanın mevcut randevularını listeler.
+Parameters: (none)
+Wait for response: true
+```
+
+---
+
+### `cancel_reservation`
+
+Cancels a specific appointment by event ID.
+
+**Requires:** `google_calendar` feature flag
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `event_id` | string | Google Calendar event ID to cancel |
+
+**Returns:** `{ cancelled, event_id }`
+
+**ElevenLabs Tool Config:**
+```
+Name: cancel_reservation
+Type: Client
+Description: Randevuyu iptal eder.
+Parameters:
+  - event_id (string, required): İptal edilecek randevunun Google Calendar event ID'si
+Wait for response: true
+```
+
+---
+
+### `reschedule_reservation`
+
+Cancels an existing appointment and creates a new one.
+
+**Requires:** `google_calendar` feature flag
+
+**Parameters:**
+| Param | Type | Description |
+|---|---|---|
+| `old_event_id` | string | Event ID to cancel |
+| `new_iso_start` | string | New start time |
+| `new_iso_end` | string | New end time |
+| `patient_name` | string (optional) | Patient name |
+| `notes` | string (optional) | Notes |
+
+**Returns:** `{ rescheduled, old_event_id, new_event_id, start, end }`
+
+**ElevenLabs Tool Config:**
+```
+Name: reschedule_reservation
+Type: Client
+Description: Mevcut randevuyu iptal edip yeni tarihte oluşturur.
+Parameters:
+  - old_event_id (string, required): İptal edilecek randevunun event ID'si
+  - new_iso_start (string, required): Yeni başlangıç zamanı, ISO 8601
+  - new_iso_end (string, required): Yeni bitiş zamanı, ISO 8601
+  - patient_name (string, optional): Hasta adı
+  - notes (string, optional): Randevu notu
+Wait for response: true
+```
+
+---
+
+### `check_patient_history`
+
+Retrieves the patient's full history: contact profile, past appointments, operator requests, and session history.
+
+**Requires:** None (always available)
+
+**Parameters:** None (patient identified by phone number)
+
+**Returns:** `{ patient_phone, contact_profile, appointments, operator_requests, total_sessions, upcoming_appointments }`
+
+**ElevenLabs Tool Config:**
+```
+Name: check_patient_history
+Type: Client
+Description: Hastanın geçmiş bilgilerini getirir: profil, randevular, önceki talepler, seans geçmişi.
+Parameters: (none)
+Wait for response: true
+```
+
+---
+
+## REF Code System
+
+REF codes are unique identifiers that link patient sessions to operator/doctor communications.
+
+**Format:** `{PREFIX}-{4 random chars}` (e.g., `R-AB3F`, `K-X7NP`)
+
+- Characters used: `ABCDEFGHJKLMNPQRSTUVWXYZ23456789` (no I/O/0/1 to avoid confusion)
+- Generated lazily on first forward in a session, stored on `session.ref_code`
+- Shared across all forwards in the same session (photos + conversations use the same REF)
+- Prefix configurable per tenant via `operator_ref_prefix` (default: `R`)
+- Uniqueness checked against both `OperatorRequest` and `WhatsAppSession` collections
+
+**Doctor reply flow:**
+1. Doctor sends WhatsApp message containing the REF code (e.g., `R-AB3F 5000 TL`)
+2. Webhook detects sender phone in known operator phones + REF pattern match
+3. Finds the most recent pending `OperatorRequest` for that REF (`sort createdAt: -1`)
+4. Updates request status, injects response into AI session
+
+---
+
+## Tenant Configuration (whatsapp_agent settings)
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `operator_ref_prefix` | string | `R` | Prefix for REF codes |
+| `operator_phone` | string | null | Doctor's phone for photo forwarding |
+| `operator_workflow_enabled` | boolean | false | Enable photo forwarding |
+| `operator_request_timeout_hours` | number | 24 | Hours before pending request expires |
+| `conversation_forwarding_phone` | string | null | Phone for conversation forwarding |
+| `operator_example_photo_enabled` | boolean | false | Enable guide photo sending |
+| `operator_example_photo_base64` | string | null | Base64 data URL of guide photo |
+| `operator_example_photo_caption` | string | `` | Caption for guide photo |
+| `outbound_call_enabled` | boolean | false | Enable outbound calls |
+| `outbound_call_phone_number_id` | string | null | ElevenLabs phone number ID |
+| `outbound_call_agent_id` | ObjectId | null | Voice agent for calls |
+
+---
+
+## Dynamic Variables (sent to ElevenLabs on WS connect)
+
+| Variable | When populated | Description |
+|---|---|---|
+| `user_summary` | Always | Patient profile summary or default text |
+| `current_date` | Always | Today's date (YYYY-MM-DD) |
+| `continuation_directive` | Reconnection + `chat_continuity` enabled | Conversation history + "don't re-introduce" instructions |
+
+Agent prompts should include `{{continuation_directive}}` for chat continuity to work.