elevenlabs-webhook-nodejs 1.0.0

package/nestjs/src/whatsapp/whatsapp-agent.service.ts

@@ -0,0 +1,2506 @@
+import { Inject, Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { InjectQueue } from '@nestjs/bullmq';
+import { EventEmitter2, OnEvent } from '@nestjs/event-emitter';
+import type { Queue } from 'bullmq';
+import WebSocket from 'ws';
+import type Redis from 'ioredis';
+import { PrismaService } from '../database/prisma.service.js';
+import { EncryptionService } from '../integrations/encryption/encryption.service.js';
+import { ElevenLabsService } from '../integrations/elevenlabs/elevenlabs.service.js';
+import { MetaWhatsAppService } from '../integrations/meta-business/meta-whatsapp.service.js';
+import { MetaInstagramService } from '../integrations/meta-business/meta-instagram.service.js';
+import { MinioService } from '../integrations/minio/minio.service.js';
+import { ElevenLabsWsAdapter } from '../tools/adapters/elevenlabs-ws.adapter.js';
+import { REDIS_CLIENT } from '../redis/redis.module.js';
+import type { ToolContext } from '../tools/tool.interfaces.js';
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+export interface IncomingMessagePayload {
+  /** Tenant ID resolved from webhook/phone number */
+  tenantId: string;
+  /** Clinic ID resolved from phone number mapping */
+  clinicId: string;
+  /** WhatsApp or Instagram external chat ID */
+  externalChatId: string;
+  /** Channel: whatsapp | instagram */
+  channel: 'whatsapp' | 'instagram';
+  /** Phone number ID (Meta Business) */
+  phoneNumberId?: string;
+  /** External account ID (for isSender echo detection) */
+  externalAccountId?: string;
+  /** Whether this message was sent by our own account */
+  isSender?: boolean;
+  /** Sender info */
+  sender: {
+    phone: string;
+    name?: string;
+    profilePicUrl?: string;
+  };
+  /** Message content */
+  message: {
+    externalId: string;
+    text: string;
+    mediaType?: string;
+    mediaKey?: string;
+    mediaMime?: string;
+    mediaFilename?: string;
+    /** Content type from the platform (e.g. 'audioMessage', 'audio') */
+    contentType?: string;
+    quotedText?: string;
+    adContext?: Record<string, any>;
+    /** Structured metadata for non-text messages (location, contacts, reaction, button reply, etc.) */
+    metadata?: Record<string, any>;
+  };
+  /** Timestamp from the platform */
+  timestamp: Date;
+}
+
+/** Resolved agent with all config needed for any AI provider */
+interface ResolvedAgent {
+  agent_id: string;
+  agent_elevenlabs_id: string;
+  agent_name: string;
+  agent_system_prompt: string;
+  agent_ai_provider: string | null;
+  agent_ai_model: string | null;
+  agent_language: string;
+  agent_greeting: string;
+  agent_temperature: number;
+  agent_max_tokens: number;
+  agent_enabled_tools: string[];
+  agent_channels: string[];
+  agent_extra_config: any;
+}
+
+/** In-memory ElevenLabs WS connection state */
+interface WsConnection {
+  ws: WebSocket;
+  agentId: string;
+  tenantId: string;
+  sessionId: string;
+  chatId: string;
+  conversationId?: string;
+  isReady: boolean;
+  readyPromise: Promise<void>;
+  readyResolve: () => void;
+}
+
+/* ------------------------------------------------------------------ */
+/*  System message patterns — Turkish + English                        */
+/* ------------------------------------------------------------------ */
+
+const SYSTEM_MESSAGE_PATTERNS: RegExp[] = [
+  /sesli arama/i,
+  /görüntülü arama/i,
+  /voice call/i,
+  /video call/i,
+  /Bu mesaj silindi/i,
+  /This message was deleted/i,
+  /kaybolan mesaj/i,
+  /disappearing message/i,
+  /uçtan uca şifrel/i,
+  /end-to-end encrypt/i,
+  /canlı konum/i,
+  /live location/i,
+  /ödeme/i,
+  /grup.*(oluştur|kurdu|değiştir|ekledi|çıkardı)/i,
+  /bir kez görüntüle/i,
+  /view once/i,
+  /WhatsApp.*(güncelle|update)/i,
+  /missed.*call/i,
+  /cevapsız.*arama/i,
+  /güvenlik kodu değişti/i,
+  /security code changed/i,
+  /numara değişti/i,
+  /changed.*(number|phone)/i,
+  /kişiyi engelle/i,
+  /blocked this contact/i,
+];
+
+/**
+ * The main AI chat engine.
+ * Manages WhatsApp/Instagram chat sessions, ElevenLabs AI WebSocket
+ * connections, grace periods, and message buffering.
+ */
+@Injectable()
+export class WhatsAppAgentService implements OnModuleDestroy {
+  private readonly logger = new Logger(WhatsAppAgentService.name);
+  private readonly messageEncryptionKey: string;
+  private readonly tokenEncryptionKey: string;
+  private readonly patientSummaryKey: string;
+
+  /** In-memory WebSocket connections keyed by chatId */
+  private readonly wsConnections = new Map<string, WsConnection>();
+
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly encryption: EncryptionService,
+    private readonly config: ConfigService,
+    private readonly eventEmitter: EventEmitter2,
+    private readonly elevenlabsService: ElevenLabsService,
+    private readonly metaWhatsApp: MetaWhatsAppService,
+    private readonly metaInstagram: MetaInstagramService,
+    private readonly minio: MinioService,
+    private readonly wsAdapter: ElevenLabsWsAdapter,
+    @Inject(REDIS_CLIENT) private readonly redis: Redis,
+    @InjectQueue('whatsapp-grace')
+    private readonly graceQueue: Queue,
+    @InjectQueue('whatsapp-message-buffer')
+    private readonly messageBufferQueue: Queue,
+    @InjectQueue('whatsapp-session-cleanup')
+    private readonly sessionCleanupQueue: Queue,
+    @InjectQueue('whatsapp-profile-update')
+    private readonly profileUpdateQueue: Queue,
+    @InjectQueue('whatsapp-session-labels')
+    private readonly sessionLabelsQueue: Queue,
+  ) {
+    this.messageEncryptionKey = this.config.getOrThrow<string>(
+      'MESSAGE_ENCRYPTION_KEY',
+    );
+    this.tokenEncryptionKey = this.config.get<string>(
+      'META_TOKEN_ENCRYPTION_KEY',
+      '',
+    );
+    this.patientSummaryKey = this.config.get<string>(
+      'PATIENT_SUMMARY_ENCRYPTION_KEY',
+      '',
+    );
+  }
+
+  onModuleDestroy() {
+    // Close all open WebSocket connections on shutdown
+    for (const [chatId] of this.wsConnections) {
+      this.closeConnection(chatId);
+    }
+  }
+
+  /* ================================================================== */
+  /*  INCOMING MESSAGE — main entry point from webhooks                  */
+  /* ================================================================== */
+
+  async handleIncomingMessage(payload: IncomingMessagePayload): Promise<void> {
+    const {
+      tenantId,
+      clinicId,
+      externalChatId,
+      channel,
+      sender,
+      message,
+    } = payload;
+
+    this.logger.debug(
+      `Incoming ${channel} message from ${sender.phone} in chat ${externalChatId}`,
+    );
+
+    // ── 1. System message filtering ──────────────────────────────────
+    if (this.isSystemMessage(message.text)) {
+      this.logger.debug(
+        `System message detected, storing without session trigger: "${message.text.substring(0, 60)}"`,
+      );
+      // Store the message for audit trail but do not trigger a session
+      await this.storeSystemMessage(tenantId, externalChatId, message, sender);
+      return;
+    }
+
+    // ── 2. Echo deduplication ────────────────────────────────────────
+    if (payload.isSender) {
+      const echoHandled = await this.handleEchoMessage(
+        tenantId,
+        externalChatId,
+        message.externalId,
+      );
+      if (echoHandled) return;
+    }
+
+    // ── 3. Resolve phone number → clinic ─────────────────────────────
+    const clinic = await this.prisma.clinic.findUnique({
+      where: { clinic_id: clinicId },
+      select: {
+        clinic_id: true,
+        clinic_tenant_id: true,
+        clinic_blacklisted_numbers: true,
+        clinic_grace_period_seconds: true,
+        clinic_fixed_first_message: true,
+        clinic_language: true,
+      },
+    });
+
+    if (!clinic) {
+      this.logger.warn(`Clinic ${clinicId} not found, dropping message`);
+      return;
+    }
+
+    // ── 3b. Voice transcription (STT) ───────────────────────────────
+    const contentType = message.contentType || message.mediaType;
+    if (
+      contentType &&
+      (contentType === 'audioMessage' || contentType === 'audio') &&
+      message.mediaKey
+    ) {
+      const sttEnabled = await this.isTenantFeatureEnabled(
+        tenantId,
+        'voice_transcription',
+      );
+
+      if (sttEnabled) {
+        try {
+          // Download audio from Meta CDN
+          const metaConn = await this.prisma.clinicMetaConnection.findFirst({
+            where: {
+              meta_clinic_id: clinicId,
+              meta_type: 'whatsapp',
+              meta_is_active: true,
+            },
+            select: {
+              meta_encrypted_access_token: true,
+            },
+          });
+
+          if (metaConn?.meta_encrypted_access_token) {
+            const accessToken = this.tokenEncryptionKey
+              ? this.encryption.decrypt(
+                  metaConn.meta_encrypted_access_token,
+                  this.tokenEncryptionKey,
+                )
+              : metaConn.meta_encrypted_access_token;
+
+            const audioBuffer = await this.metaWhatsApp.downloadMedia(
+              message.mediaKey,
+              accessToken,
+            );
+
+            const sttResult = await this.elevenlabsService.transcribe(
+              audioBuffer,
+              clinic.clinic_language || 'tr',
+            );
+
+            if (sttResult.text?.trim()) {
+              message.text = sttResult.text;
+              message.contentType = 'transcribedAudio';
+              message.mediaType = 'transcribedAudio';
+
+              // Log STT usage (fire-and-forget)
+              this.prisma.sttUsage
+                .create({
+                  data: {
+                    stt_tenant_id: tenantId,
+                    stt_clinic_id: clinicId,
+                    stt_duration_seconds: 0, // Meta doesn't provide duration in webhook
+                    stt_character_count: sttResult.text.length,
+                    stt_language: clinic.clinic_language || 'tr',
+                  },
+                })
+                .catch((err) =>
+                  this.logger.warn(
+                    `Failed to log STT usage: ${(err as Error).message}`,
+                  ),
+                );
+
+              this.logger.debug(
+                `STT transcribed audio for chat ${externalChatId}: "${sttResult.text.substring(0, 60)}"`,
+              );
+            }
+          }
+        } catch (err: any) {
+          this.logger.warn(
+            `STT transcription failed for chat ${externalChatId}: ${err.message}. Keeping original media label.`,
+          );
+          // Keep the original media label text — do not modify message
+        }
+      }
+    }
+
+    // ── 4. Patient find-or-create ────────────────────────────────────
+    const patient = await this.findOrCreatePatient(
+      tenantId,
+      clinicId,
+      sender.phone,
+      sender.name,
+      channel,
+    );
+
+    // ── 5. Chat find-or-create ───────────────────────────────────────
+    const chat = await this.findOrCreateChat(
+      tenantId,
+      clinicId,
+      externalChatId,
+      channel,
+      patient.patient_id,
+      sender,
+      payload.phoneNumberId,
+    );
+
+    // ── 6. Blacklist check ───────────────────────────────────────────
+    if (clinic.clinic_blacklisted_numbers.includes(sender.phone)) {
+      this.logger.debug(`Blacklisted number ${sender.phone} — storing but not triggering`);
+      await this.storeEncryptedMessage(
+        chat.chat_id,
+        chat.chat_active_session_id,
+        tenantId,
+        message,
+        sender,
+      );
+      return;
+    }
+
+    // ── 7. Encrypt and store message ─────────────────────────────────
+    const dbMessage = await this.storeEncryptedMessage(
+      chat.chat_id,
+      chat.chat_active_session_id,
+      tenantId,
+      message,
+      sender,
+    );
+
+    // Update chat metadata
+    const chatUpdates: any = {
+      chat_last_message_at: new Date(),
+      chat_last_message_preview: message.text.substring(0, 100),
+      chat_message_count: { increment: 1 },
+      chat_contact_name: sender.name || chat.chat_contact_name,
+    };
+    // For Instagram, update contact_phone with display name if it's still a raw scoped ID
+    if (channel === 'instagram' && sender.name && /^\d+$/.test(chat.chat_contact_phone)) {
+      chatUpdates.chat_contact_phone = sender.name;
+    }
+    await this.prisma.whatsappChat.update({
+      where: { chat_id: chat.chat_id },
+      data: chatUpdates,
+    });
+
+    // ── 8. Session routing ───────────────────────────────────────────
+    if (chat.chat_active_session_id) {
+      const session = await this.prisma.whatsappSession.findUnique({
+        where: { session_id: chat.chat_active_session_id },
+        select: {
+          session_id: true,
+          session_status: true,
+          session_taken_over_by_id: true,
+        },
+      });
+
+      if (session) {
+        if (session.session_status === 'waiting') {
+          // Timer already running — just store (message already stored above)
+          this.logger.debug(
+            `Session ${session.session_id} is waiting, message stored`,
+          );
+        } else if (session.session_status === 'active') {
+          // Taken over by human? Don't trigger AI
+          if (session.session_taken_over_by_id) {
+            this.logger.debug(
+              `Session ${session.session_id} taken over by human, skipping AI`,
+            );
+          } else {
+            // Enqueue message-buffer job (debounce for multi-message bursts)
+            await this.bufferMessage(session.session_id, dbMessage.msg_id);
+          }
+        }
+        // If resolved, fall through to new session creation below is skipped
+        // because chat_active_session_id exists
+      }
+    } else {
+      // No active session — start a new one
+      const session = await this.startSession(
+        chat.chat_id,
+        tenantId,
+        clinicId,
+      );
+
+      // Link message to the new session
+      await this.prisma.whatsappMessage.update({
+        where: { msg_id: dbMessage.msg_id },
+        data: { msg_session_id: session.session_id },
+      });
+
+      // Update chat active session
+      await this.prisma.whatsappChat.update({
+        where: { chat_id: chat.chat_id },
+        data: { chat_active_session_id: session.session_id },
+      });
+
+      // Send fixed first message if configured (fire-and-forget)
+      if (clinic.clinic_fixed_first_message) {
+        const receiverIdFromChat = externalChatId.split('@')[1];
+        this.sendFixedFirstMessage(
+          clinicId,
+          sender.phone,
+          clinic.clinic_fixed_first_message,
+          session.session_id,
+          chat.chat_id,
+          tenantId,
+          receiverIdFromChat,
+        ).catch((err) =>
+          this.logger.error(
+            `Failed to send fixed first message: ${err.message}`,
+          ),
+        );
+      }
+    }
+
+    // ── 9. Emit event for real-time dashboard ────────────────────────
+    this.eventEmitter.emit('whatsapp.message.received', {
+      chatId: chat.chat_id,
+      messageId: dbMessage.msg_id,
+      tenantId,
+      clinicId,
+    });
+  }
+
+  /* ================================================================== */
+  /*  START SESSION                                                      */
+  /* ================================================================== */
+
+  async startSession(chatId: string, tenantId: string, clinicId: string) {
+    const clinic = await this.prisma.clinic.findUnique({
+      where: { clinic_id: clinicId },
+      select: { clinic_grace_period_seconds: true },
+    });
+
+    const gracePeriodMs = (clinic?.clinic_grace_period_seconds ?? 180) * 1000;
+    const graceDeadline = new Date(Date.now() + gracePeriodMs);
+
+    const session = await this.prisma.whatsappSession.create({
+      data: {
+        session_chat_id: chatId,
+        session_tenant_id: tenantId,
+        session_clinic_id: clinicId,
+        session_status: 'waiting',
+        session_grace_deadline: graceDeadline,
+      },
+    });
+
+    this.logger.debug(
+      `Created session ${session.session_id} (waiting) for chat ${chatId}, grace=${gracePeriodMs}ms`,
+    );
+
+    // Schedule grace period expiry job
+    await this.graceQueue.add(
+      'grace-expire',
+      { sessionId: session.session_id },
+      {
+        delay: gracePeriodMs,
+        jobId: `grace-${session.session_id}`,
+        removeOnComplete: true,
+        removeOnFail: 100,
+      },
+    );
+
+    return session;
+  }
+
+  /* ================================================================== */
+  /*  ACTIVATE SESSION — transition waiting → active, connect to AI      */
+  /* ================================================================== */
+
+  async activateSession(sessionId: string): Promise<void> {
+    const session = await this.prisma.whatsappSession.findUnique({
+      where: { session_id: sessionId },
+      include: {
+        chat: {
+          select: {
+            chat_id: true,
+            chat_external_id: true,
+            chat_channel: true,
+            chat_contact_phone: true,
+            chat_contact_name: true,
+            chat_phone_id: true,
+          },
+        },
+        clinic: {
+          select: {
+            clinic_id: true,
+            clinic_tenant_id: true,
+            clinic_timezone: true,
+          },
+        },
+      },
+    });
+
+    if (!session || session.session_status !== 'waiting') {
+      this.logger.warn(
+        `Cannot activate session ${sessionId}: not found or not in waiting status`,
+      );
+      return;
+    }
+
+    // Transition to active
+    await this.prisma.whatsappSession.update({
+      where: { session_id: sessionId },
+      data: { session_status: 'active' },
+    });
+
+    this.logger.debug(`Session ${sessionId} activated`);
+
+    // Store WS connection metadata in Redis for awareness across processes
+    const redisKey = `ws:conn:${session.chat.chat_id}`;
+    await this.redis.hmset(redisKey, {
+      sessionId,
+      tenantId: session.session_tenant_id,
+      clinicId: session.session_clinic_id,
+      chatId: session.chat.chat_id,
+      activatedAt: new Date().toISOString(),
+    });
+    await this.redis.expire(redisKey, 3600); // 1 hour TTL
+
+    // Resolve agent for this clinic and trigger initial AI response
+    const agent = await this.resolveAgent(
+      session.session_clinic_id,
+      session.session_tenant_id,
+    );
+
+    if (agent) {
+      // Collect all buffered messages from the waiting period
+      const bufferedMessages = await this.prisma.whatsappMessage.findMany({
+        where: {
+          msg_session_id: sessionId,
+          msg_sender: 'contact',
+        },
+        orderBy: { msg_created_at: 'asc' },
+        select: { msg_text: true, msg_media_type: true },
+      });
+
+      const texts: string[] = [];
+      for (const msg of bufferedMessages) {
+        try {
+          const decrypted = this.encryption.decrypt(
+            msg.msg_text,
+            this.messageEncryptionKey,
+          );
+          if (decrypted.trim()) {
+            texts.push(decrypted);
+          } else if (msg.msg_media_type) {
+            texts.push(`[${msg.msg_media_type}]`);
+          }
+        } catch {
+          texts.push('[mesaj okunamadi]');
+        }
+      }
+
+      const combinedText = texts.join('\n');
+
+      if (combinedText.trim()) {
+        // Fire-and-forget the AI response trigger
+        this.triggerAiResponse(
+          sessionId,
+          session.chat.chat_id,
+          combinedText,
+        ).catch((err) =>
+          this.logger.error(
+            `Failed to trigger AI for session ${sessionId}: ${err.message}`,
+            err.stack,
+          ),
+        );
+      }
+    } else {
+      this.logger.warn(
+        `No active agent found for clinic ${session.session_clinic_id}, session ${sessionId} won't connect to AI`,
+      );
+    }
+
+    this.eventEmitter.emit('whatsapp.session.activated', {
+      sessionId,
+      chatId: session.session_chat_id,
+      tenantId: session.session_tenant_id,
+      clinicId: session.session_clinic_id,
+    });
+
+    this.eventEmitter.emit('chat.session.status', {
+      sessionId,
+      chatId: session.session_chat_id,
+      tenantId: session.session_tenant_id,
+      status: 'active',
+    });
+  }
+
+  /* ================================================================== */
+  /*  RESOLVE SESSION                                                    */
+  /* ================================================================== */
+
+  async resolveSession(
+    sessionId: string,
+    resolvedBy: 'human' | 'ai_timeout' | 'timeout' | 'manual',
+  ): Promise<void> {
+    const session = await this.prisma.whatsappSession.findUnique({
+      where: { session_id: sessionId },
+      include: {
+        chat: {
+          select: {
+            chat_id: true,
+            chat_patient_id: true,
+          },
+        },
+      },
+    });
+
+    if (!session) {
+      this.logger.warn(`Session ${sessionId} not found for resolve`);
+      return;
+    }
+
+    if (session.session_status === 'resolved') {
+      this.logger.debug(`Session ${sessionId} already resolved`);
+      return;
+    }
+
+    // Close ElevenLabs WebSocket if connected
+    this.closeConnection(session.session_chat_id);
+
+    // Fetch ElevenLabs conversation cost if we have a conversation ID
+    let elCost: number | undefined;
+    if (session.session_el_conversation_id) {
+      try {
+        const costData = await this.elevenlabsService.getConversationCost(
+          session.session_el_conversation_id,
+        );
+        elCost = costData?.total_cost_usd ?? costData?.cost;
+      } catch (err: any) {
+        this.logger.warn(
+          `Failed to fetch conversation cost for ${session.session_el_conversation_id}: ${err.message}`,
+        );
+      }
+    }
+
+    // Update session status
+    await this.prisma.whatsappSession.update({
+      where: { session_id: sessionId },
+      data: {
+        session_status: 'resolved',
+        session_resolved_by: resolvedBy,
+        session_resolved_at: new Date(),
+        ...(elCost !== undefined ? { session_el_cost: elCost } : {}),
+      },
+    });
+
+    // Clear chat active session
+    await this.prisma.whatsappChat.update({
+      where: { chat_id: session.session_chat_id },
+      data: { chat_active_session_id: null },
+    });
+
+    // Delete Redis WS state
+    await this.redis.del(`ws:conn:${session.session_chat_id}`);
+
+    this.logger.debug(
+      `Session ${sessionId} resolved (by: ${resolvedBy})`,
+    );
+
+    // Update patient stats
+    if (session.chat.chat_patient_id) {
+      this.prisma.patient
+        .update({
+          where: { patient_id: session.chat.chat_patient_id },
+          data: {
+            patient_last_contact_at: new Date(),
+            patient_total_sessions: { increment: 1 },
+          },
+        })
+        .catch((err) =>
+          this.logger.error(
+            `Failed to update patient stats: ${err.message}`,
+          ),
+        );
+    }
+
+    // Schedule post-session jobs
+    await Promise.all([
+      this.profileUpdateQueue.add(
+        'update-profile',
+        {
+          sessionId,
+          tenantId: session.session_tenant_id,
+          chatId: session.session_chat_id,
+        },
+        { removeOnComplete: true, removeOnFail: 100 },
+      ),
+      this.sessionLabelsQueue.add(
+        'extract-labels',
+        {
+          sessionId,
+          tenantId: session.session_tenant_id,
+        },
+        { removeOnComplete: true, removeOnFail: 100 },
+      ),
+    ]);
+
+    this.eventEmitter.emit('chat.session.status', {
+      sessionId,
+      chatId: session.session_chat_id,
+      tenantId: session.session_tenant_id,
+      status: 'resolved',
+      resolvedBy,
+    });
+
+    this.eventEmitter.emit('whatsapp.session.resolved', {
+      sessionId,
+      chatId: session.session_chat_id,
+      tenantId: session.session_tenant_id,
+      resolvedBy,
+    });
+  }
+
+  /* ================================================================== */
+  /*  TRIGGER AI RESPONSE — connect to ElevenLabs and send message       */
+  /* ================================================================== */
+
+  async triggerAiResponse(
+    sessionId: string,
+    chatId: string,
+    combinedText: string,
+  ): Promise<void> {
+    // Load session with all needed relations
+    const session = await this.prisma.whatsappSession.findUnique({
+      where: { session_id: sessionId },
+      include: {
+        chat: {
+          select: {
+            chat_id: true,
+            chat_external_id: true,
+            chat_contact_phone: true,
+            chat_contact_name: true,
+            chat_phone_id: true,
+            chat_channel: true,
+            chat_patient_id: true,
+          },
+        },
+        clinic: {
+          select: {
+            clinic_id: true,
+            clinic_tenant_id: true,
+            clinic_timezone: true,
+          },
+        },
+      },
+    });
+
+    if (!session) {
+      this.logger.warn(`Session ${sessionId} not found for AI trigger`);
+      return;
+    }
+
+    if (session.session_status !== 'active') {
+      this.logger.debug(
+        `Session ${sessionId} not active (${session.session_status}), skipping AI trigger`,
+      );
+      return;
+    }
+
+    // If session is taken over by a human, skip AI
+    if (session.session_taken_over_by_id) {
+      this.logger.debug(
+        `Session ${sessionId} is taken over, skipping AI trigger`,
+      );
+      return;
+    }
+
+    // Resolve the agent for this clinic
+    const agent = await this.resolveAgent(
+      session.session_clinic_id,
+      session.session_tenant_id,
+    );
+
+    if (!agent) {
+      this.logger.warn(
+        `No agent found for clinic ${session.session_clinic_id}, cannot trigger AI`,
+      );
+      return;
+    }
+
+    // Get or create the WS connection
+    const conn = await this.getOrCreateConnection(
+      chatId,
+      agent.agent_elevenlabs_id,
+      session.session_tenant_id,
+      sessionId,
+    );
+
+    if (!conn) {
+      this.logger.error(
+        `Failed to establish WS connection for chat ${chatId}`,
+      );
+      return;
+    }
+
+    // Wait for the connection to be ready
+    try {
+      await conn.readyPromise;
+    } catch (err: any) {
+      this.logger.error(
+        `WS connection for chat ${chatId} failed to become ready: ${err.message}`,
+      );
+      this.closeConnection(chatId);
+      return;
+    }
+
+    // Build and send chat context
+    const chatContext = await this.buildChatContext(sessionId);
+    if (chatContext) {
+      this.wsSend(conn, {
+        type: 'contextual_update',
+        text: chatContext,
+      });
+    }
+
+    // Send the user message
+    this.wsSend(conn, {
+      type: 'user_message',
+      text: combinedText,
+    });
+
+    // Update session last interaction
+    await this.prisma.whatsappSession.update({
+      where: { session_id: sessionId },
+      data: { session_el_last_interaction: new Date() },
+    });
+  }
+
+  /* ================================================================== */
+  /*  BUILD CHAT CONTEXT                                                 */
+  /* ================================================================== */
+
+  async buildChatContext(sessionId: string): Promise<string> {
+    // Fetch all messages in the session
+    const messages = await this.prisma.whatsappMessage.findMany({
+      where: { msg_session_id: sessionId },
+      orderBy: { msg_created_at: 'asc' },
+      select: {
+        msg_sender: true,
+        msg_text: true,
+        msg_media_type: true,
+        msg_created_at: true,
+      },
+    });
+
+    // Fetch operator requests for the session
+    const operatorRequests = await this.prisma.operatorRequest.findMany({
+      where: { opreq_session_id: sessionId },
+      orderBy: { opreq_created_at: 'asc' },
+      select: {
+        opreq_ref_code: true,
+        opreq_status: true,
+        opreq_request_message: true,
+        opreq_operator_response: true,
+        opreq_forwarded_at: true,
+        opreq_responded_at: true,
+        opreq_created_at: true,
+      },
+    });
+
+    // Build timeline entries
+    interface TimelineEntry {
+      timestamp: Date;
+      text: string;
+    }
+    const timeline: TimelineEntry[] = [];
+
+    // Add message entries
+    for (const msg of messages) {
+      let text: string;
+      try {
+        text = this.encryption.decrypt(msg.msg_text, this.messageEncryptionKey);
+      } catch {
+        text = msg.msg_media_type ? `[${msg.msg_media_type}]` : '[mesaj okunamadi]';
+      }
+
+      if (!text.trim() && msg.msg_media_type) {
+        text = `[${msg.msg_media_type}]`;
+      }
+
+      const senderLabel = this.getSenderLabel(msg.msg_sender);
+      timeline.push({
+        timestamp: msg.msg_created_at,
+        text: `${senderLabel}: ${text}`,
+      });
+    }
+
+    // Add operator request events
+    for (const req of operatorRequests) {
+      timeline.push({
+        timestamp: req.opreq_created_at,
+        text: `[SISTEM: Doktora yonlendirildi - REF: ${req.opreq_ref_code}${
+          req.opreq_request_message ? ` - Not: ${req.opreq_request_message}` : ''
+        }]`,
+      });
+
+      if (req.opreq_status === 'responded' && req.opreq_responded_at) {
+        timeline.push({
+          timestamp: req.opreq_responded_at,
+          text: `[SISTEM: Doktor yaniti alindi - REF: ${req.opreq_ref_code} - Yanit: ${req.opreq_operator_response ?? ''}]`,
+        });
+      }
+
+      if (req.opreq_status === 'expired') {
+        timeline.push({
+          timestamp: req.opreq_responded_at ?? req.opreq_created_at,
+          text: `[SISTEM: Doktor yanit suresi doldu - REF: ${req.opreq_ref_code}]`,
+        });
+      }
+    }
+
+    // Sort by timestamp
+    timeline.sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+    // Format the context string
+    return timeline.map((entry) => entry.text).join('\n');
+  }
+
+  /* ================================================================== */
+  /*  TAKEOVER — human takes over from AI                                */
+  /* ================================================================== */
+
+  async takeOver(chatId: string, userId: string): Promise<void> {
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: { chat_id: chatId },
+      select: { chat_active_session_id: true, chat_tenant_id: true },
+    });
+
+    if (!chat?.chat_active_session_id) {
+      this.logger.warn(`No active session on chat ${chatId} for takeover`);
+      return;
+    }
+
+    const sessionId = chat.chat_active_session_id;
+
+    // Close AI WebSocket connection
+    this.closeConnection(chatId);
+
+    // Cancel any pending message buffer jobs for this session
+    try {
+      const jobs = await this.messageBufferQueue.getJobs([
+        'waiting',
+        'delayed',
+        'active',
+      ]);
+      for (const job of jobs) {
+        if (job.data?.sessionId === sessionId) {
+          await job.remove();
+        }
+      }
+    } catch (err: any) {
+      this.logger.warn(
+        `Failed to cancel buffer jobs for session ${sessionId}: ${err.message}`,
+      );
+    }
+
+    await this.prisma.whatsappSession.update({
+      where: { session_id: sessionId },
+      data: {
+        session_taken_over_by_id: userId,
+        session_taken_over_at: new Date(),
+      },
+    });
+
+    this.logger.log(
+      `Session ${sessionId} taken over by user ${userId}`,
+    );
+
+    this.eventEmitter.emit('whatsapp.session.takeover', {
+      sessionId,
+      chatId,
+      userId,
+      tenantId: chat.chat_tenant_id,
+    });
+
+    this.eventEmitter.emit('chat.session.status', {
+      sessionId,
+      chatId,
+      tenantId: chat.chat_tenant_id,
+      status: 'active',
+      takenOverBy: userId,
+    });
+  }
+
+  /* ================================================================== */
+  /*  RELEASE — release session back to AI                               */
+  /* ================================================================== */
+
+  async releaseSession(chatId: string): Promise<void> {
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: { chat_id: chatId },
+      select: {
+        chat_active_session_id: true,
+        chat_tenant_id: true,
+      },
+    });
+
+    if (!chat?.chat_active_session_id) {
+      this.logger.warn(`No active session on chat ${chatId} for release`);
+      return;
+    }
+
+    const sessionId = chat.chat_active_session_id;
+
+    await this.prisma.whatsappSession.update({
+      where: { session_id: sessionId },
+      data: {
+        session_taken_over_by_id: null,
+        session_taken_over_at: null,
+      },
+    });
+
+    this.logger.log(`Session ${sessionId} released back to AI`);
+
+    // AI resumes on the next patient message. No need to proactively
+    // reconnect here — the next incoming message will trigger a buffer
+    // job which calls triggerAiResponse.
+
+    this.eventEmitter.emit('whatsapp.session.released', {
+      sessionId,
+      chatId,
+    });
+
+    this.eventEmitter.emit('chat.session.status', {
+      sessionId,
+      chatId,
+      tenantId: chat.chat_tenant_id,
+      status: 'active',
+      takenOverBy: null,
+    });
+  }
+
+  /* ================================================================== */
+  /*  SEND HUMAN MESSAGE                                                 */
+  /* ================================================================== */
+
+  async sendHumanMessage(
+    chatId: string,
+    userId: string,
+    text: string,
+  ): Promise<void> {
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: { chat_id: chatId },
+      include: {
+        clinic: {
+          select: {
+            clinic_id: true,
+            clinic_tenant_id: true,
+          },
+        },
+      },
+    });
+
+    if (!chat) {
+      this.logger.warn(`Chat ${chatId} not found for sending message`);
+      return;
+    }
+
+    // Extract recipient and receiver from external ID (format: sender@receiver)
+    const [recipientId, receiverId] = chat.chat_external_id.split('@');
+
+    // Send message via Meta Business API (WhatsApp or Instagram)
+    const metaResult = chat.chat_channel === 'instagram'
+      ? await this.sendViaInstagram(chat.clinic.clinic_id, recipientId, text, receiverId)
+      : await this.sendViaMeta(chat.clinic.clinic_id, recipientId, text, receiverId);
+
+    // Resolve user name
+    let senderName = '';
+    try {
+      const user = await this.prisma.user.findUnique({
+        where: { user_id: userId },
+        select: { user_first_name: true, user_last_name: true },
+      });
+      if (user) {
+        senderName = [user.user_first_name, user.user_last_name]
+          .filter(Boolean)
+          .join(' ');
+      }
+    } catch {
+      // Non-critical
+    }
+
+    // Persist the message
+    const encryptedText = this.encryption.encrypt(
+      text,
+      this.messageEncryptionKey,
+    );
+
+    const msg = await this.prisma.whatsappMessage.create({
+      data: {
+        msg_chat_id: chatId,
+        msg_session_id: chat.chat_active_session_id,
+        msg_tenant_id: chat.chat_tenant_id,
+        msg_external_id: metaResult?.messages?.[0]?.id ?? null,
+        msg_sender: 'human',
+        msg_sender_name: senderName,
+        msg_sender_user_id: userId,
+        msg_text: encryptedText,
+      },
+    });
+
+    // Update chat metadata
+    await this.prisma.whatsappChat.update({
+      where: { chat_id: chatId },
+      data: {
+        chat_last_message_at: new Date(),
+        chat_last_message_preview: text.substring(0, 100),
+        chat_message_count: { increment: 1 },
+      },
+    });
+
+    this.eventEmitter.emit('whatsapp.message.sent', {
+      chatId,
+      messageId: msg.msg_id,
+      tenantId: chat.chat_tenant_id,
+    });
+
+    this.eventEmitter.emit('chat.message.created', {
+      chatId,
+      messageId: msg.msg_id,
+      tenantId: chat.chat_tenant_id,
+      sender: 'human',
+    });
+  }
+
+  /* ================================================================== */
+  /*  SEND HUMAN MEDIA                                                   */
+  /* ================================================================== */
+
+  async sendHumanMedia(
+    chatId: string,
+    userId: string,
+    buffer: Buffer,
+    mimeType: string,
+    filename: string,
+    caption?: string,
+  ): Promise<void> {
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: { chat_id: chatId },
+      include: {
+        clinic: { select: { clinic_id: true, clinic_tenant_id: true } },
+      },
+    });
+
+    if (!chat) {
+      this.logger.warn(`Chat ${chatId} not found for sending media`);
+      return;
+    }
+
+    const [recipientId, receiverId] = chat.chat_external_id.split('@');
+    const mediaType = this.resolveMediaType(mimeType);
+
+    let metaResult: any = null;
+
+    if (chat.chat_channel === 'instagram') {
+      // Instagram: upload isn't supported via API, use URL-based approach
+      // Store in MinIO first, then send via URL
+      const minioKey = `chat-media-out/${chat.chat_tenant_id}/${Date.now()}-${filename}`;
+      await this.minio.putObject(minioKey, buffer, mimeType);
+      const mediaUrl = await this.minio.presignedGetObject(minioKey, 86400);
+
+      const metaConn = await this.getInstagramConnection(chat.clinic.clinic_id, receiverId);
+      if (metaConn) {
+        metaResult = await this.metaInstagram.sendMedia(
+          metaConn.pageId,
+          recipientId,
+          mediaUrl,
+          metaConn.token,
+        );
+      }
+    } else {
+      // WhatsApp: upload to Meta first, then send by ID
+      const metaConn = await this.getWhatsAppConnection(chat.clinic.clinic_id, receiverId);
+      if (metaConn) {
+        const mediaId = await this.metaWhatsApp.uploadMedia(
+          metaConn.phoneNumberId,
+          buffer,
+          mimeType,
+          filename,
+          metaConn.token,
+        );
+        metaResult = await this.metaWhatsApp.sendMediaById(
+          metaConn.phoneNumberId,
+          recipientId,
+          mediaType,
+          mediaId,
+          caption,
+          metaConn.token,
+          filename,
+        );
+      }
+    }
+
+    // Resolve sender name
+    let senderName = '';
+    try {
+      const user = await this.prisma.user.findUnique({
+        where: { user_id: userId },
+        select: { user_first_name: true, user_last_name: true },
+      });
+      if (user) senderName = [user.user_first_name, user.user_last_name].filter(Boolean).join(' ');
+    } catch {}
+
+    // Store in MinIO for display
+    const minioKey = `chat-media/${chat.chat_tenant_id}/${metaResult?.messages?.[0]?.id || Date.now()}`;
+    this.minio.putObject(minioKey, buffer, mimeType).catch(() => {});
+
+    // Persist message
+    const encryptedCaption = this.encryption.encrypt(
+      caption || '',
+      this.messageEncryptionKey,
+    );
+
+    const msg = await this.prisma.whatsappMessage.create({
+      data: {
+        msg_chat_id: chatId,
+        msg_session_id: chat.chat_active_session_id,
+        msg_tenant_id: chat.chat_tenant_id,
+        msg_external_id: metaResult?.messages?.[0]?.id ?? null,
+        msg_sender: 'human',
+        msg_sender_name: senderName,
+        msg_sender_user_id: userId,
+        msg_text: encryptedCaption,
+        msg_media_type: mediaType,
+        msg_media_key: minioKey,
+        msg_media_mime: mimeType,
+        msg_media_filename: filename,
+      },
+    });
+
+    await this.prisma.whatsappChat.update({
+      where: { chat_id: chatId },
+      data: {
+        chat_last_message_at: new Date(),
+        chat_last_message_preview: caption || `[${mediaType}]`,
+        chat_message_count: { increment: 1 },
+      },
+    });
+
+    this.eventEmitter.emit('chat.message.created', {
+      chatId,
+      messageId: msg.msg_id,
+      tenantId: chat.chat_tenant_id,
+      sender: 'human',
+    });
+  }
+
+  private resolveMediaType(mimeType: string): 'image' | 'video' | 'document' | 'audio' {
+    if (mimeType.startsWith('image/')) return 'image';
+    if (mimeType.startsWith('video/')) return 'video';
+    if (mimeType.startsWith('audio/')) return 'audio';
+    return 'document';
+  }
+
+  private async getWhatsAppConnection(clinicId: string, metaPhoneNumberId?: string) {
+    const where: any = { meta_clinic_id: clinicId, meta_type: 'whatsapp', meta_is_active: true };
+    if (metaPhoneNumberId) where.meta_phone_number_id = metaPhoneNumberId;
+
+    const conn = await this.prisma.clinicMetaConnection.findFirst({
+      where,
+      select: { meta_phone_number_id: true, meta_encrypted_access_token: true },
+    });
+    if (!conn?.meta_phone_number_id || !conn?.meta_encrypted_access_token) return null;
+
+    const token = this.tokenEncryptionKey
+      ? this.encryption.decrypt(conn.meta_encrypted_access_token, this.tokenEncryptionKey)
+      : conn.meta_encrypted_access_token;
+    return { phoneNumberId: conn.meta_phone_number_id, token };
+  }
+
+  private async getInstagramConnection(clinicId: string, igPageId?: string) {
+    const where: any = { meta_clinic_id: clinicId, meta_type: 'instagram', meta_is_active: true };
+    if (igPageId) where.meta_instagram_page_id = igPageId;
+
+    const conn = await this.prisma.clinicMetaConnection.findFirst({
+      where,
+      select: { meta_instagram_page_id: true, meta_facebook_page_id: true, meta_encrypted_access_token: true },
+    });
+    const pageId = conn?.meta_facebook_page_id || conn?.meta_instagram_page_id;
+    if (!pageId || !conn?.meta_encrypted_access_token) return null;
+
+    const token = this.tokenEncryptionKey
+      ? this.encryption.decrypt(conn.meta_encrypted_access_token, this.tokenEncryptionKey)
+      : conn.meta_encrypted_access_token;
+    return { pageId, token };
+  }
+
+  /* ================================================================== */
+  /*  INJECT OPERATOR RESPONSE — called by OperatorService               */
+  /* ================================================================== */
+
+  async injectOperatorResponse(
+    sessionId: string,
+    refCode: string,
+    responseText: string,
+  ): Promise<void> {
+    const session = await this.prisma.whatsappSession.findUnique({
+      where: { session_id: sessionId },
+      select: {
+        session_id: true,
+        session_status: true,
+        session_chat_id: true,
+        session_tenant_id: true,
+        session_clinic_id: true,
+      },
+    });
+
+    if (!session || session.session_status !== 'active') {
+      this.logger.warn(
+        `Cannot inject operator response for session ${sessionId}: not active`,
+      );
+      return;
+    }
+
+    const conn = this.wsConnections.get(session.session_chat_id);
+    const contextText =
+      `[SISTEM: Doktor yaniti alindi - REF: ${refCode} - Yanit: ${responseText}]`;
+
+    if (conn && conn.ws.readyState === WebSocket.OPEN) {
+      // WS still alive — send contextual update
+      this.wsSend(conn, {
+        type: 'contextual_update',
+        text: contextText,
+      });
+      this.logger.debug(
+        `Injected operator response for ${refCode} into live WS`,
+      );
+    } else {
+      // WS dead — recreate connection with full chat context
+      this.logger.debug(
+        `WS dead for chat ${session.session_chat_id}, recreating for operator response`,
+      );
+
+      const agent = await this.resolveAgent(
+        session.session_clinic_id,
+        session.session_tenant_id,
+      );
+
+      if (!agent) {
+        this.logger.error(
+          `No agent found when recreating WS for operator response`,
+        );
+        return;
+      }
+
+      const newConn = await this.getOrCreateConnection(
+        session.session_chat_id,
+        agent.agent_elevenlabs_id,
+        session.session_tenant_id,
+        sessionId,
+      );
+
+      if (!newConn) return;
+
+      try {
+        await newConn.readyPromise;
+      } catch {
+        this.logger.error(`Failed to reconnect WS for operator response`);
+        return;
+      }
+
+      // Send full chat history as context
+      const chatContext = await this.buildChatContext(sessionId);
+      if (chatContext) {
+        this.wsSend(newConn, { type: 'contextual_update', text: chatContext });
+      }
+
+      // Send the operator response as a user message so the AI acts on it
+      this.wsSend(newConn, {
+        type: 'contextual_update',
+        text: contextText,
+      });
+    }
+  }
+
+  /* ================================================================== */
+  /*  EVENT LISTENERS                                                    */
+  /* ================================================================== */
+
+  /** Handle buffered messages from MessageBufferProcessor */
+  @OnEvent('whatsapp.messages.buffered')
+  async onMessagesBuffered(payload: {
+    sessionId: string;
+    chatId: string;
+    tenantId: string;
+    clinicId: string;
+    combinedText: string;
+    messageCount: number;
+  }): Promise<void> {
+    this.logger.debug(
+      `Buffered ${payload.messageCount} messages for session ${payload.sessionId}`,
+    );
+    await this.triggerAiResponse(
+      payload.sessionId,
+      payload.chatId,
+      payload.combinedText,
+    );
+  }
+
+  /* ================================================================== */
+  /*  ELEVENLABS WEBSOCKET MANAGEMENT                                    */
+  /* ================================================================== */
+
+  /**
+   * Get an existing WS connection or create a new one.
+   * Returns null if the connection cannot be established.
+   */
+  private async getOrCreateConnection(
+    chatId: string,
+    agentId: string,
+    tenantId: string,
+    sessionId: string,
+  ): Promise<WsConnection | null> {
+    // Check if we already have a live connection
+    const existing = this.wsConnections.get(chatId);
+    if (existing && existing.ws.readyState === WebSocket.OPEN) {
+      return existing;
+    }
+
+    // Clean up stale connection if any
+    if (existing) {
+      this.closeConnection(chatId);
+    }
+
+    try {
+      // Detect reconnection: session already has a conversation_id
+      const sessionData = await this.prisma.whatsappSession.findUnique({
+        where: { session_id: sessionId },
+        select: {
+          session_el_conversation_id: true,
+          session_el_prev_conversation_ids: true,
+        },
+      });
+      const isReconnect = !!sessionData?.session_el_conversation_id;
+
+      // Get signed URL from ElevenLabs
+      const { signed_url } = await this.elevenlabsService.getSignedUrl(agentId);
+
+      // Build patient summary for dynamic variables
+      const patientSummary = await this.getPatientSummary(sessionId);
+
+      // Build continuation directive for reconnection
+      let continuationDirective = '';
+      if (isReconnect) {
+        try {
+          const chatContext = await this.buildChatContext(sessionId);
+          // Find last AI message for the directive
+          const lastAiMsg = await this.prisma.whatsappMessage.findFirst({
+            where: {
+              msg_session_id: sessionId,
+              msg_sender: 'ai',
+            },
+            orderBy: { msg_created_at: 'desc' },
+            select: { msg_text: true },
+          });
+
+          let lastAiText = '';
+          if (lastAiMsg) {
+            try {
+              lastAiText = this.encryption.decrypt(
+                lastAiMsg.msg_text,
+                this.messageEncryptionKey,
+              );
+            } catch {
+              lastAiText = '[mesaj okunamadi]';
+            }
+          }
+
+          continuationDirective = [
+            'ONEMLI -- KONUSMA DEVAMI:',
+            'Bu hasta ile onceden baslamis bir konusma var. Teknik bir baglanti yenilenmesi yasandi.',
+            'Kendini TANITMA. Selam VERME. Hosgeldin DEME. Konusmaya kaldigin yerden DEVAM ET.',
+            lastAiText
+              ? `En son gonderdigin mesaj: "${lastAiText}"`
+              : '',
+            '',
+            'Konusma gecmisi:',
+            chatContext,
+          ]
+            .filter(Boolean)
+            .join('\n');
+
+          // Push old conversation_id to prev_conversation_ids
+          const prevIds = sessionData.session_el_prev_conversation_ids ?? [];
+          prevIds.push(sessionData.session_el_conversation_id!);
+          await this.prisma.whatsappSession.update({
+            where: { session_id: sessionId },
+            data: {
+              session_el_prev_conversation_ids: prevIds,
+              session_el_conversation_id: null, // Will be set when new WS is ready
+            },
+          });
+
+          this.logger.debug(
+            `WS reconnect for session ${sessionId}, continuation directive built (${continuationDirective.length} chars)`,
+          );
+        } catch (err: any) {
+          this.logger.warn(
+            `Failed to build continuation directive for session ${sessionId}: ${err.message}`,
+          );
+        }
+      }
+
+      // Create ready promise for synchronization
+      let readyResolve!: () => void;
+      let readyReject!: (err: Error) => void;
+      const readyPromise = new Promise<void>((resolve, reject) => {
+        readyResolve = resolve;
+        readyReject = reject;
+      });
+
+      const ws = new WebSocket(`${signed_url}&textOnly=true`);
+
+      const conn: WsConnection = {
+        ws,
+        agentId,
+        tenantId,
+        sessionId,
+        chatId,
+        isReady: false,
+        readyPromise,
+        readyResolve,
+      };
+
+      this.wsConnections.set(chatId, conn);
+
+      // Capture reconnect state and context for the open handler closure
+      const _isReconnect = isReconnect;
+      const _continuationDirective = continuationDirective;
+
+      // Setup event handlers
+      ws.on('open', () => {
+        this.logger.debug(`WS opened for chat ${chatId} (reconnect=${_isReconnect})`);
+
+        // Send conversation initiation data
+        ws.send(
+          JSON.stringify({
+            type: 'conversation_initiation_client_data',
+            conversation_config_override: {},
+            dynamic_variables: {
+              user_summary: patientSummary,
+              current_date: new Date().toISOString().split('T')[0],
+              continuation_directive: _continuationDirective,
+            },
+          }),
+        );
+      });
+
+      ws.on('message', (data) => {
+        this.handleWsMessage(chatId, data.toString()).catch((err) =>
+          this.logger.error(
+            `WS message handler error for chat ${chatId}: ${err.message}`,
+            err.stack,
+          ),
+        );
+      });
+
+      ws.on('close', (code, reason) => {
+        this.logger.debug(
+          `WS closed for chat ${chatId}: code=${code} reason=${reason.toString()}`,
+        );
+        this.wsConnections.delete(chatId);
+        this.redis
+          .del(`ws:conn:${chatId}`)
+          .catch(() => { /* ignore */ });
+
+        if (!conn.isReady) {
+          readyReject(new Error(`WS closed before ready: ${code}`));
+        }
+      });
+
+      ws.on('error', (err) => {
+        this.logger.error(
+          `WS error for chat ${chatId}: ${err.message}`,
+        );
+        if (!conn.isReady) {
+          readyReject(err);
+        }
+      });
+
+      // Set a timeout for the ready state
+      const readyTimeout = setTimeout(() => {
+        if (!conn.isReady) {
+          readyReject(new Error('WS ready timeout (15s)'));
+          this.closeConnection(chatId);
+        }
+      }, 15_000);
+
+      // Clean up timeout when ready
+      readyPromise.then(() => clearTimeout(readyTimeout)).catch(() => clearTimeout(readyTimeout));
+
+      return conn;
+    } catch (err: any) {
+      this.logger.error(
+        `Failed to create WS connection for chat ${chatId}: ${err.message}`,
+        err.stack,
+      );
+      return null;
+    }
+  }
+
+  /** Close a WS connection and clean up. */
+  private closeConnection(chatId: string): void {
+    const conn = this.wsConnections.get(chatId);
+    if (!conn) return;
+
+    try {
+      if (
+        conn.ws.readyState === WebSocket.OPEN ||
+        conn.ws.readyState === WebSocket.CONNECTING
+      ) {
+        conn.ws.close(1000, 'session_ended');
+      }
+    } catch {
+      // Ignore close errors
+    }
+
+    this.wsConnections.delete(chatId);
+    this.redis.del(`ws:conn:${chatId}`).catch(() => { /* ignore */ });
+
+    this.logger.debug(`Closed WS connection for chat ${chatId}`);
+  }
+
+  /** Route incoming WS messages from ElevenLabs. */
+  private async handleWsMessage(
+    chatId: string,
+    rawData: string,
+  ): Promise<void> {
+    let msg: any;
+    try {
+      msg = JSON.parse(rawData);
+    } catch {
+      this.logger.warn(`Non-JSON WS message for chat ${chatId}: ${rawData.substring(0, 100)}`);
+      return;
+    }
+
+    const conn = this.wsConnections.get(chatId);
+    if (!conn) {
+      this.logger.warn(
+        `Received WS message for unknown chat ${chatId}: type=${msg.type}`,
+      );
+      return;
+    }
+
+    switch (msg.type) {
+      case 'conversation_initiation_metadata': {
+        // Connection is ready — store conversation ID
+        conn.conversationId = msg.conversation_id;
+        conn.isReady = true;
+        conn.readyResolve();
+
+        // Persist the conversation ID on the session
+        if (msg.conversation_id) {
+          await this.prisma.whatsappSession.update({
+            where: { session_id: conn.sessionId },
+            data: {
+              session_el_conversation_id: msg.conversation_id,
+              session_el_conversation_created: new Date(),
+            },
+          });
+        }
+
+        this.logger.debug(
+          `WS ready for chat ${chatId}, conversationId=${msg.conversation_id}`,
+        );
+        break;
+      }
+
+      case 'agent_response': {
+        // AI responded — send to patient and store
+        const responseText = msg.agent_response_text ?? msg.text ?? '';
+        if (!responseText.trim()) break;
+
+        await this.handleAgentResponse(conn, responseText);
+        break;
+      }
+
+      case 'client_tool_call': {
+        // Delegate to tool registry via the WS adapter
+        await this.handleClientToolCall(conn, msg);
+        break;
+      }
+
+      case 'ping': {
+        // Respond with pong to keep alive
+        this.wsSend(conn, { type: 'pong' });
+        break;
+      }
+
+      case 'user_transcript':
+      case 'internal_tentative_agent_response':
+        // Informational — ignore
+        break;
+
+      default:
+        this.logger.debug(
+          `Unhandled WS message type for chat ${chatId}: ${msg.type}`,
+        );
+    }
+  }
+
+  /** Handle an AI agent_response: send to patient + store. */
+  private async handleAgentResponse(
+    conn: WsConnection,
+    responseText: string,
+  ): Promise<void> {
+    const { chatId, sessionId, tenantId } = conn;
+
+    // Send to patient via Meta API (fire-and-forget)
+    this.sendAiResponseToPatient(chatId, responseText).catch((err) =>
+      this.logger.error(
+        `Failed to send AI response for chat ${chatId}: ${err.message}`,
+      ),
+    );
+
+    // Encrypt and store as AI message
+    const encryptedText = this.encryption.encrypt(
+      responseText,
+      this.messageEncryptionKey,
+    );
+
+    const msg = await this.prisma.whatsappMessage.create({
+      data: {
+        msg_chat_id: chatId,
+        msg_session_id: sessionId,
+        msg_tenant_id: tenantId,
+        msg_sender: 'ai',
+        msg_sender_name: 'AI',
+        msg_text: encryptedText,
+      },
+    });
+
+    // Update chat metadata
+    await this.prisma.whatsappChat.update({
+      where: { chat_id: chatId },
+      data: {
+        chat_last_message_at: new Date(),
+        chat_last_message_preview: responseText.substring(0, 100),
+        chat_message_count: { increment: 1 },
+      },
+    });
+
+    // Update session message count and last interaction
+    await this.prisma.whatsappSession.update({
+      where: { session_id: sessionId },
+      data: {
+        session_message_count: { increment: 1 },
+        session_el_last_interaction: new Date(),
+      },
+    });
+
+    // Emit for real-time dashboard
+    this.eventEmitter.emit('whatsapp.message.sent', {
+      chatId,
+      messageId: msg.msg_id,
+      tenantId,
+    });
+
+    this.eventEmitter.emit('chat.message.created', {
+      chatId,
+      messageId: msg.msg_id,
+      tenantId,
+      sender: 'ai',
+    });
+  }
+
+  /** Handle a client_tool_call from ElevenLabs. */
+  private async handleClientToolCall(
+    conn: WsConnection,
+    msg: any,
+  ): Promise<void> {
+    const { chatId, sessionId, tenantId } = conn;
+
+    // Load chat for context
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: { chat_id: chatId },
+      select: {
+        chat_contact_phone: true,
+        chat_contact_name: true,
+        chat_clinic_id: true,
+        chat_channel: true,
+        chat_patient_id: true,
+        chat_phone_id: true,
+      },
+    });
+
+    if (!chat) {
+      this.logger.error(`Chat ${chatId} not found for tool call`);
+      // Send error result back to ElevenLabs
+      this.wsSend(conn, {
+        type: 'client_tool_result',
+        tool_call_id: msg.tool_call_id,
+        result: 'Internal error: chat not found',
+        is_error: true,
+      });
+      return;
+    }
+
+    // Build tool context
+    const toolCtx: ToolContext = {
+      tenantId,
+      clinicId: chat.chat_clinic_id,
+      patientPhone: chat.chat_contact_phone,
+      patientName: chat.chat_contact_name ?? '',
+      patientId: chat.chat_patient_id ?? undefined,
+      channel: chat.chat_channel as 'whatsapp' | 'instagram',
+      channelMetadata: {
+        chatId,
+        sessionId,
+        conversationId: conn.conversationId,
+        agentId: conn.agentId,
+        phoneNumberId: chat.chat_phone_id ?? undefined,
+      },
+    };
+
+    // Delegate to the WS adapter which handles the tool registry
+    const result = await this.wsAdapter.handleToolCall(
+      {
+        tool_call_id: msg.tool_call_id,
+        tool_name: msg.tool_name,
+        parameters: msg.parameters ?? {},
+      },
+      toolCtx,
+    );
+
+    // Send result back to ElevenLabs
+    this.wsSend(conn, result);
+  }
+
+  /* ================================================================== */
+  /*  PRIVATE HELPERS                                                    */
+  /* ================================================================== */
+
+  /** Check if message text matches any system message pattern. */
+  private isSystemMessage(text: string): boolean {
+    if (!text || !text.trim()) return false;
+    return SYSTEM_MESSAGE_PATTERNS.some((pattern) => pattern.test(text));
+  }
+
+  /**
+   * Handle echo (isSender) messages.
+   * Returns true if the message was handled (should be skipped).
+   */
+  private async handleEchoMessage(
+    tenantId: string,
+    externalChatId: string,
+    msgExternalId: string,
+  ): Promise<boolean> {
+    // Check if this is a message we sent via our API (match by external ID)
+    const ourMessage = await this.prisma.whatsappMessage.findFirst({
+      where: {
+        msg_external_id: msgExternalId,
+        msg_tenant_id: tenantId,
+        msg_sender: { in: ['ai', 'human', 'system'] },
+      },
+    });
+
+    if (ourMessage) {
+      // This is an echo of a message we sent — skip entirely
+      this.logger.debug(`Echo of our message ${msgExternalId}, skipping`);
+      return true;
+    }
+
+    // This was sent by a real person from the business phone (not via our API).
+    // Check if there's a session in 'waiting' — resolve as 'human'
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: {
+        chat_tenant_id_chat_external_id: {
+          chat_tenant_id: tenantId,
+          chat_external_id: externalChatId,
+        },
+      },
+      select: { chat_active_session_id: true },
+    });
+
+    if (chat?.chat_active_session_id) {
+      const session = await this.prisma.whatsappSession.findUnique({
+        where: { session_id: chat.chat_active_session_id },
+        select: { session_status: true, session_id: true },
+      });
+
+      if (session?.session_status === 'waiting') {
+        this.logger.log(
+          `Human replied from business phone, resolving session ${session.session_id}`,
+        );
+        await this.resolveSession(session.session_id, 'human');
+      }
+    }
+
+    return true;
+  }
+
+  /** Store a system message (audit trail only, no session trigger). */
+  private async storeSystemMessage(
+    tenantId: string,
+    externalChatId: string,
+    message: IncomingMessagePayload['message'],
+    sender: IncomingMessagePayload['sender'],
+  ): Promise<void> {
+    // Find the chat (don't create one for system messages)
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: {
+        chat_tenant_id_chat_external_id: {
+          chat_tenant_id: tenantId,
+          chat_external_id: externalChatId,
+        },
+      },
+      select: { chat_id: true, chat_active_session_id: true },
+    });
+
+    if (!chat) {
+      // No existing chat — don't create one for a system message
+      return;
+    }
+
+    const encryptedText = this.encryption.encrypt(
+      message.text,
+      this.messageEncryptionKey,
+    );
+
+    await this.prisma.whatsappMessage.create({
+      data: {
+        msg_chat_id: chat.chat_id,
+        msg_session_id: chat.chat_active_session_id,
+        msg_tenant_id: tenantId,
+        msg_external_id: message.externalId,
+        msg_sender: 'system',
+        msg_sender_name: sender.name ?? '',
+        msg_text: encryptedText,
+      },
+    });
+  }
+
+  /** Encrypt and store an incoming message. */
+  private async storeEncryptedMessage(
+    chatId: string,
+    sessionId: string | null,
+    tenantId: string,
+    message: IncomingMessagePayload['message'],
+    sender: IncomingMessagePayload['sender'],
+  ) {
+    const encryptedText = this.encryption.encrypt(
+      message.text,
+      this.messageEncryptionKey,
+    );
+
+    const encryptedQuoted = message.quotedText
+      ? this.encryption.encrypt(message.quotedText, this.messageEncryptionKey)
+      : null;
+
+    return this.prisma.whatsappMessage.create({
+      data: {
+        msg_chat_id: chatId,
+        msg_session_id: sessionId,
+        msg_tenant_id: tenantId,
+        msg_external_id: message.externalId,
+        msg_sender: 'contact',
+        msg_sender_name: sender.name ?? '',
+        msg_text: encryptedText,
+        msg_media_type: message.mediaType,
+        msg_media_key: message.mediaKey,
+        msg_media_mime: message.mediaMime,
+        msg_media_filename: message.mediaFilename,
+        msg_ad_context: message.adContext as any,
+        msg_metadata: message.metadata as any,
+        msg_quoted_text: encryptedQuoted,
+      },
+    });
+  }
+
+  private async findOrCreatePatient(
+    tenantId: string,
+    clinicId: string,
+    phone: string,
+    name?: string,
+    channel: 'whatsapp' | 'instagram' = 'whatsapp',
+  ) {
+    let patient = await this.prisma.patient.findUnique({
+      where: {
+        patient_tenant_id_patient_phone: {
+          patient_tenant_id: tenantId,
+          patient_phone: phone,
+        },
+      },
+    });
+
+    if (!patient) {
+      const displayName = name || 'Bilinmiyor';
+      patient = await this.prisma.patient.create({
+        data: {
+          patient_tenant_id: tenantId,
+          patient_clinic_id: clinicId,
+          patient_phone: phone,
+          patient_display_name: displayName,
+          patient_first_name: name ?? '',
+          patient_last_name: '',
+          patient_source: channel,
+          patient_last_contact_at: new Date(),
+        },
+      });
+      this.logger.debug(
+        `Created new patient ${patient.patient_id} for ${phone}`,
+      );
+    } else {
+      // Update last contact + name if we now have a better one
+      const updates: any = { patient_last_contact_at: new Date() };
+      if (name && (!patient.patient_display_name || patient.patient_display_name === 'Bilinmiyor' || patient.patient_display_name === patient.patient_phone)) {
+        updates.patient_display_name = name;
+        updates.patient_first_name = name;
+      }
+      await this.prisma.patient.update({
+        where: { patient_id: patient.patient_id },
+        data: updates,
+      });
+    }
+
+    return patient;
+  }
+
+  private async findOrCreateChat(
+    tenantId: string,
+    clinicId: string,
+    externalChatId: string,
+    channel: 'whatsapp' | 'instagram',
+    patientId: string,
+    sender: { phone: string; name?: string },
+    phoneNumberId?: string,
+  ) {
+    let chat = await this.prisma.whatsappChat.findUnique({
+      where: {
+        chat_tenant_id_chat_external_id: {
+          chat_tenant_id: tenantId,
+          chat_external_id: externalChatId,
+        },
+      },
+    });
+
+    if (!chat) {
+      // Resolve phone number record — phoneNumberId may be Meta's internal ID
+      let phoneId: string | null = null;
+      if (phoneNumberId) {
+        // Try direct match first (actual phone number string)
+        let phone = await this.prisma.phoneNumber.findFirst({
+          where: { phone_tenant_id: tenantId, phone_number: phoneNumberId },
+          select: { phone_id: true },
+        });
+        // Fall back: resolve via ClinicMetaConnection (Meta phone number ID)
+        if (!phone) {
+          const metaConn = await this.prisma.clinicMetaConnection.findFirst({
+            where: { meta_phone_number_id: phoneNumberId, meta_is_active: true },
+            select: { meta_display_phone: true },
+          });
+          if (metaConn?.meta_display_phone) {
+            phone = await this.prisma.phoneNumber.findFirst({
+              where: { phone_tenant_id: tenantId, phone_number: metaConn.meta_display_phone },
+              select: { phone_id: true },
+            });
+          }
+        }
+        phoneId = phone?.phone_id ?? null;
+      }
+
+      chat = await this.prisma.whatsappChat.create({
+        data: {
+          chat_tenant_id: tenantId,
+          chat_clinic_id: clinicId,
+          chat_patient_id: patientId,
+          chat_channel: channel,
+          chat_external_id: externalChatId,
+          chat_phone_id: phoneId,
+          chat_contact_name: sender.name || 'Bilinmiyor',
+          chat_contact_phone: sender.name && channel === 'instagram' ? sender.name : sender.phone,
+        },
+      });
+      this.logger.debug(
+        `Created new chat ${chat.chat_id} for external ${externalChatId}`,
+      );
+    }
+
+    return chat;
+  }
+
+  private static readonly AGENT_CACHE_PREFIX = 'agent_config:';
+  private static readonly AGENT_CACHE_TTL = 300; // 5 minutes
+
+  /** Resolve the agent for a clinic (cached in Redis). */
+  private async resolveAgent(
+    clinicId: string,
+    tenantId: string,
+  ): Promise<ResolvedAgent | null> {
+    const cacheKey = `${WhatsAppAgentService.AGENT_CACHE_PREFIX}${tenantId}:${clinicId}`;
+
+    // Check cache
+    const cached = await this.redis.get(cacheKey);
+    if (cached) {
+      if (cached === 'null') return null;
+      return JSON.parse(cached) as ResolvedAgent;
+    }
+
+    // DB lookup
+    const agent = await this.prisma.agent.findFirst({
+      where: {
+        agent_is_active: true,
+        agent_status: 'production',
+        OR: [
+          { agent_clinic_id: clinicId },
+          { agent_tenant_id: tenantId, agent_clinic_id: null },
+        ],
+      },
+      orderBy: {
+        agent_clinic_id: { sort: 'desc', nulls: 'last' },
+      },
+      select: {
+        agent_id: true,
+        agent_elevenlabs_id: true,
+        agent_name: true,
+        agent_system_prompt: true,
+        agent_ai_provider: true,
+        agent_ai_model: true,
+        agent_language: true,
+        agent_greeting: true,
+        agent_temperature: true,
+        agent_max_tokens: true,
+        agent_enabled_tools: true,
+        agent_channels: true,
+        agent_extra_config: true,
+      },
+    });
+
+    // Cache result (even null to avoid repeated DB misses)
+    await this.redis.setex(
+      cacheKey,
+      WhatsAppAgentService.AGENT_CACHE_TTL,
+      agent ? JSON.stringify(agent) : 'null',
+    );
+
+    return agent;
+  }
+
+  /** Invalidate agent cache for a tenant (call after agent config changes). */
+  async invalidateAgentCache(tenantId: string): Promise<void> {
+    const keys = await this.redis.keys(`${WhatsAppAgentService.AGENT_CACHE_PREFIX}${tenantId}:*`);
+    if (keys.length > 0) {
+      await this.redis.del(...keys);
+      this.logger.debug(`Invalidated ${keys.length} agent cache entries for tenant ${tenantId}`);
+    }
+  }
+
+  /** Get the decrypted patient summary for dynamic variables. */
+  private async getPatientSummary(sessionId: string): Promise<string> {
+    try {
+      const session = await this.prisma.whatsappSession.findUnique({
+        where: { session_id: sessionId },
+        select: {
+          chat: {
+            select: {
+              chat_patient_id: true,
+            },
+          },
+        },
+      });
+
+      if (!session?.chat.chat_patient_id) return '';
+
+      const patient = await this.prisma.patient.findUnique({
+        where: { patient_id: session.chat.chat_patient_id },
+        select: {
+          patient_display_name: true,
+          patient_phone: true,
+          patient_ai_summary: true,
+          patient_total_sessions: true,
+          patient_tags: true,
+        },
+      });
+
+      if (!patient) return '';
+
+      const parts: string[] = [
+        `Hasta: ${patient.patient_display_name}`,
+        `Telefon: ${patient.patient_phone}`,
+        `Toplam gorusme: ${patient.patient_total_sessions}`,
+      ];
+
+      if (patient.patient_tags.length > 0) {
+        parts.push(`Etiketler: ${patient.patient_tags.join(', ')}`);
+      }
+
+      // Decrypt AI summary if available
+      if (patient.patient_ai_summary && this.patientSummaryKey) {
+        try {
+          const summary = this.encryption.decrypt(
+            patient.patient_ai_summary,
+            this.patientSummaryKey,
+          );
+          if (summary.trim()) {
+            parts.push(`Onceki notlar: ${summary}`);
+          }
+        } catch {
+          // Non-critical — skip summary if decryption fails
+        }
+      }
+
+      return parts.join('\n');
+    } catch (err: any) {
+      this.logger.warn(
+        `Failed to build patient summary for session ${sessionId}: ${err.message}`,
+      );
+      return '';
+    }
+  }
+
+  /** Send AI response text to the patient via Meta Business API. */
+  private async sendAiResponseToPatient(
+    chatId: string,
+    text: string,
+  ): Promise<void> {
+    const chat = await this.prisma.whatsappChat.findUnique({
+      where: { chat_id: chatId },
+      select: {
+        chat_external_id: true,
+        chat_clinic_id: true,
+        chat_channel: true,
+      },
+    });
+
+    if (!chat) return;
+
+    const [recipientId, receiverId] = chat.chat_external_id.split('@');
+
+    if (chat.chat_channel === 'instagram') {
+      await this.sendViaInstagram(chat.chat_clinic_id, recipientId, text, receiverId);
+    } else {
+      await this.sendViaMeta(chat.chat_clinic_id, recipientId, text, receiverId);
+    }
+  }
+
+  /** Send a text message via Meta Business API. Resolves the access token. */
+  private async sendViaMeta(
+    clinicId: string,
+    recipientPhone: string,
+    text: string,
+    metaPhoneNumberId?: string,
+  ): Promise<any> {
+    // Find the exact Meta connection by phone number ID, or fall back to any active one
+    const where: any = {
+      meta_clinic_id: clinicId,
+      meta_type: 'whatsapp',
+      meta_is_active: true,
+    };
+    if (metaPhoneNumberId) {
+      where.meta_phone_number_id = metaPhoneNumberId;
+    }
+    const metaConnection = await this.prisma.clinicMetaConnection.findFirst({
+      where,
+      select: {
+        meta_phone_number_id: true,
+        meta_encrypted_access_token: true,
+      },
+    });
+
+    if (
+      !metaConnection?.meta_phone_number_id ||
+      !metaConnection?.meta_encrypted_access_token
+    ) {
+      this.logger.warn(
+        `No active Meta WhatsApp connection for clinic ${clinicId}`,
+      );
+      return null;
+    }
+
+    let accessToken: string;
+    try {
+      accessToken = this.tokenEncryptionKey
+        ? this.encryption.decrypt(
+            metaConnection.meta_encrypted_access_token,
+            this.tokenEncryptionKey,
+          )
+        : metaConnection.meta_encrypted_access_token;
+    } catch {
+      this.logger.error(
+        `Failed to decrypt Meta access token for clinic ${clinicId}`,
+      );
+      return null;
+    }
+
+    return this.metaWhatsApp.sendMessage(
+      metaConnection.meta_phone_number_id,
+      recipientPhone,
+      text,
+      accessToken,
+    );
+  }
+
+  /** Send a text message via Instagram Messenger API. */
+  private async sendViaInstagram(
+    clinicId: string,
+    recipientId: string,
+    text: string,
+    igPageId?: string,
+  ): Promise<any> {
+    const where: any = {
+      meta_clinic_id: clinicId,
+      meta_type: 'instagram',
+      meta_is_active: true,
+    };
+    if (igPageId) {
+      where.meta_instagram_page_id = igPageId;
+    }
+    const metaConnection = await this.prisma.clinicMetaConnection.findFirst({
+      where,
+      select: {
+        meta_instagram_page_id: true,
+        meta_facebook_page_id: true,
+        meta_encrypted_access_token: true,
+      },
+    });
+
+    // Instagram messaging API is called on the Facebook Page ID
+    const pageId = metaConnection?.meta_facebook_page_id || metaConnection?.meta_instagram_page_id;
+
+    if (
+      !pageId ||
+      !metaConnection?.meta_encrypted_access_token
+    ) {
+      this.logger.warn(
+        `No active Meta Instagram connection for clinic ${clinicId}`,
+      );
+      return null;
+    }
+
+    let accessToken: string;
+    try {
+      accessToken = this.tokenEncryptionKey
+        ? this.encryption.decrypt(
+            metaConnection.meta_encrypted_access_token,
+            this.tokenEncryptionKey,
+          )
+        : metaConnection.meta_encrypted_access_token;
+    } catch {
+      this.logger.error(
+        `Failed to decrypt Meta Instagram token for clinic ${clinicId}`,
+      );
+      return null;
+    }
+
+    return this.metaInstagram.sendMessage(
+      pageId,
+      recipientId,
+      text,
+      accessToken,
+    );
+  }
+
+  /** Send the fixed first message configured on the clinic. */
+  private async sendFixedFirstMessage(
+    clinicId: string,
+    recipientPhone: string,
+    fixedMessage: string,
+    sessionId: string,
+    chatId: string,
+    tenantId: string,
+    metaPhoneNumberId?: string,
+  ): Promise<void> {
+    const metaResult = await this.sendViaMeta(
+      clinicId,
+      recipientPhone,
+      fixedMessage,
+      metaPhoneNumberId,
+    );
+
+    if (!metaResult) return;
+
+    // Store the fixed message
+    const encryptedText = this.encryption.encrypt(
+      fixedMessage,
+      this.messageEncryptionKey,
+    );
+
+    const msg = await this.prisma.whatsappMessage.create({
+      data: {
+        msg_chat_id: chatId,
+        msg_session_id: sessionId,
+        msg_tenant_id: tenantId,
+        msg_external_id: metaResult?.messages?.[0]?.id ?? null,
+        msg_sender: 'system',
+        msg_sender_name: 'System',
+        msg_text: encryptedText,
+      },
+    });
+
+    await this.prisma.whatsappChat.update({
+      where: { chat_id: chatId },
+      data: {
+        chat_last_message_at: new Date(),
+        chat_last_message_preview: fixedMessage.substring(0, 100),
+        chat_message_count: { increment: 1 },
+      },
+    });
+
+    this.eventEmitter.emit('chat.message.created', {
+      chatId,
+      messageId: msg.msg_id,
+      tenantId,
+      sender: 'system',
+    });
+  }
+
+  /** Enqueue a message-buffer BullMQ job. */
+  private async bufferMessage(
+    sessionId: string,
+    messageId: string,
+  ): Promise<void> {
+    await this.messageBufferQueue.add(
+      'buffer',
+      { sessionId, messageId },
+      {
+        delay: 1500, // 1.5s debounce for multi-message bursts
+        removeOnComplete: true,
+        removeOnFail: 100,
+      },
+    );
+  }
+
+  /** Get a human-readable sender label. */
+  private getSenderLabel(
+    sender: string,
+  ): string {
+    switch (sender) {
+      case 'contact':
+        return 'Hasta';
+      case 'ai':
+        return 'AI';
+      case 'human':
+        return 'Operator';
+      case 'system':
+        return 'Sistem';
+      default:
+        return sender;
+    }
+  }
+
+  /** Check if a tenant has a specific feature enabled. */
+  private async isTenantFeatureEnabled(
+    tenantId: string,
+    feature: string,
+  ): Promise<boolean> {
+    try {
+      const tenant = await this.prisma.tenant.findUnique({
+        where: { tenant_id: tenantId },
+        select: { tenant_enabled_features: true },
+      });
+      return tenant?.tenant_enabled_features?.includes(feature) ?? false;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Send a JSON message over a WS connection. */
+  private wsSend(conn: WsConnection, data: Record<string, any>): void {
+    if (conn.ws.readyState !== WebSocket.OPEN) {
+      this.logger.warn(
+        `Cannot send WS message for chat ${conn.chatId}: not open (state=${conn.ws.readyState})`,
+      );
+      return;
+    }
+    try {
+      conn.ws.send(JSON.stringify(data));
+    } catch (err: any) {
+      this.logger.error(
+        `Failed to send WS message for chat ${conn.chatId}: ${err.message}`,
+      );
+    }
+  }
+}