elevenlabs-webhook-nodejs 1.0.0

package/src/modules/whatsapp/whatsapp.routes.ts

@@ -0,0 +1,1435 @@
+import type { FastifyInstance } from 'fastify';
+import mongoose from 'mongoose';
+import { requireRole, requireFeature } from '../../plugins/rbac';
+import WhatsAppChat from './whatsapp-chat.model';
+import WhatsAppSession from './whatsapp-session.model';
+import WhatsAppMessage from './whatsapp-message.model';
+import unipileService from '../../services/unipile.service';
+import whatsappAgentService from '../../services/whatsapp-agent.service';
+import Tenant from '../tenants/tenant.model';
+import Agent from '../agents/agent.model';
+import WhatsAppContactProfile from './whatsapp-contact-profile.model';
+import googleCalendarService from '../../services/google-calendar.service';
+import Appointment from './appointment.model';
+import logger from '../../utils/logger';
+
+/**
+ * Derives backward-compatible virtual fields (mode, session_status, taken_over_by, etc.)
+ * from the chat's active session, for frontend consumption.
+ */
+async function enrichChat(chatDoc: any): Promise<any> {
+  const chat = typeof chatDoc.toObject === 'function' ? chatDoc.toObject() : { ...chatDoc };
+
+  let session: any = null;
+  if (chat.active_session_id) {
+    session = await WhatsAppSession.findById(chat.active_session_id)
+      .populate('taken_over_by', 'name email')
+      .lean();
+    if (session && session.status === 'resolved') {
+      session = null;
+    }
+  }
+
+  if (!session) {
+    chat.mode = chat.is_closed ? 'closed' : 'ai';
+    chat.session_status = 'idle';
+    chat.taken_over_by = null;
+    chat.taken_over_at = null;
+    chat.session_started_at = null;
+    chat.session_grace_deadline = null;
+    chat.session_resolved_by = null;
+  } else if (session.status === 'waiting') {
+    chat.mode = 'human';
+    chat.session_status = 'waiting';
+    chat.taken_over_by = null;
+    chat.taken_over_at = null;
+    chat.session_started_at = session.started_at;
+    chat.session_grace_deadline = session.grace_deadline;
+    chat.session_resolved_by = null;
+  } else if (session.status === 'active') {
+    const isHuman = !!(session.taken_over_by || session.taken_over_at);
+    chat.mode = isHuman ? 'human' : 'ai';
+    chat.session_status = 'idle';
+    chat.taken_over_by = session.taken_over_by || null;
+    chat.taken_over_at = session.taken_over_at || null;
+    chat.session_started_at = session.started_at;
+    chat.session_grace_deadline = null;
+    chat.session_resolved_by = null;
+  }
+
+  // Remove internal-only fields
+  delete chat.active_session_id;
+  delete chat.is_closed;
+
+  // Remove aggregation pipeline temporary fields
+  delete chat._session;
+  delete chat._activeSession;
+  delete chat._mode;
+
+  return chat;
+}
+
+/**
+ * Enrich multiple chats in parallel.
+ */
+async function enrichChats(chatDocs: any[]): Promise<any[]> {
+  return Promise.all(chatDocs.map(c => enrichChat(c)));
+}
+
+export default async function whatsappRoutes(fastify: FastifyInstance): Promise<void> {
+  fastify.addHook('preHandler', fastify.authenticate);
+  fastify.addHook('preHandler', requireFeature('whatsapp_agent'));
+
+  // ─── Connection Management ───────────────────────────────
+
+  // POST /whatsapp/connect — Initiate WhatsApp QR code connection
+  fastify.post('/connect', {
+    preHandler: [requireRole('admin')],
+  }, async (request, reply) => {
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    const provider = unipileService.getProviderForTenant(tenant);
+    const existingAccountId = tenant?.settings?.whatsapp_agent?.unipile_account_id;
+
+    // Try to reconnect existing account first
+    if (existingAccountId) {
+      try {
+        const result = await unipileService.reconnectAccount(provider, existingAccountId);
+        logger.info('WhatsApp reconnect result', { provider, accountId: existingAccountId, result: JSON.stringify(result).substring(0, 500) });
+
+        await Tenant.findByIdAndUpdate(request.user.tenant_id, {
+          $set: { 'settings.whatsapp_agent.unipile_account_status': 'pending' }
+        });
+
+        return result;
+      } catch (err) {
+        logger.warn('Reconnect failed, creating new account', {
+          accountId: existingAccountId,
+          error: (err as Error).message,
+        });
+      }
+    }
+
+    // Create new account
+    const result = await unipileService.connectWhatsApp(provider);
+    logger.info('WhatsApp connect result keys', { keys: Object.keys(result), result: JSON.stringify(result).substring(0, 500) });
+
+    const newAccountId = (result.account_id || '') as string;
+
+    if (newAccountId) {
+      await Tenant.findByIdAndUpdate(request.user.tenant_id, {
+        $set: {
+          'settings.whatsapp_agent.unipile_account_id': newAccountId,
+          'settings.whatsapp_agent.unipile_account_status': 'pending',
+        }
+      });
+
+      // Update existing chats to use new account ID so they're not orphaned
+      const chatsToMigrate = await WhatsAppChat.find({
+        tenant_id: request.user.tenant_id,
+        unipile_account_id: { $ne: newAccountId },
+      });
+
+      if (chatsToMigrate.length > 0) {
+        const isBaileys = provider === 'baileys';
+        let migrated = 0;
+        for (const chat of chatsToMigrate) {
+          const updates: Record<string, string> = {
+            unipile_account_id: newAccountId,
+          };
+
+          if (isBaileys && chat.unipile_chat_id) {
+            const colonIdx = chat.unipile_chat_id.indexOf(':');
+            if (colonIdx !== -1 && chat.unipile_chat_id.includes('@')) {
+              // Existing composite ID — re-prefix
+              const jid = chat.unipile_chat_id.slice(colonIdx + 1);
+              updates.unipile_chat_id = `${newAccountId}:${jid}`;
+            } else if (chat.unipile_chat_id.includes('@')) {
+              // Plain JID from Unipile — add composite prefix for Baileys
+              updates.unipile_chat_id = `${newAccountId}:${chat.unipile_chat_id}`;
+            }
+          }
+
+          await WhatsAppChat.updateOne({ _id: chat._id }, { $set: updates });
+          migrated++;
+        }
+
+        logger.info('Migrated chats to new account ID', {
+          from: existingAccountId ?? '(none)',
+          to: newAccountId,
+          provider,
+          count: migrated,
+        });
+      }
+    }
+
+    // Forward the full response — Unipile may return checkpoint, qr_code, object, etc.
+    return result;
+  });
+
+  // GET /whatsapp/connection-status — Check connection status
+  fastify.get('/connection-status', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request) => {
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    const provider = unipileService.getProviderForTenant(tenant);
+    const accountId = tenant?.settings?.whatsapp_agent?.unipile_account_id;
+
+    // Helper to extract google calendar fields (never exposes encrypted_refresh_token)
+    const gcalFields = (t: typeof tenant) => {
+      const gc = t?.settings?.whatsapp_agent?.google_calendar;
+      return {
+        google_calendar_connected: gc?.connected ?? false,
+        google_calendar_email: gc?.google_email ?? null,
+        google_calendar_calendar_id: gc?.calendar_id ?? null,
+        google_calendar_calendar_name: gc?.calendar_name ?? null,
+        google_calendar_appointment_duration_minutes: gc?.appointment_duration_minutes ?? 30,
+        google_calendar_working_hours: gc?.working_hours ?? [],
+        google_calendar_blocked_dates: gc?.blocked_dates ?? [],
+        google_calendar_timezone: gc?.timezone ?? 'Europe/Istanbul',
+      };
+    };
+
+    if (!accountId) {
+      return {
+        connected: false,
+        status: 'not_configured',
+        bridge_provider: provider,
+        ai_shift_enabled: tenant?.settings?.whatsapp_agent?.ai_shift_enabled ?? false,
+        ai_shift_schedule: tenant?.settings?.whatsapp_agent?.ai_shift_schedule ?? [],
+        grace_period_seconds: tenant?.settings?.whatsapp_agent?.grace_period_seconds ?? 180,
+        fixed_first_message_enabled: tenant?.settings?.whatsapp_agent?.fixed_first_message_enabled ?? false,
+        fixed_first_message: tenant?.settings?.whatsapp_agent?.fixed_first_message ?? '',
+        operator_workflow_enabled: tenant?.settings?.whatsapp_agent?.operator_workflow_enabled ?? false,
+        operator_phone: tenant?.settings?.whatsapp_agent?.operator_phone ?? null,
+        operator_ref_prefix: tenant?.settings?.whatsapp_agent?.operator_ref_prefix ?? 'R',
+        operator_request_timeout_hours: tenant?.settings?.whatsapp_agent?.operator_request_timeout_hours ?? 24,
+        operator_example_photo_enabled: tenant?.settings?.whatsapp_agent?.operator_example_photo_enabled ?? false,
+        has_example_photo: !!tenant?.settings?.whatsapp_agent?.operator_example_photo_base64,
+        operator_example_photo_base64: tenant?.settings?.whatsapp_agent?.operator_example_photo_base64 ?? null,
+        operator_example_photo_caption: tenant?.settings?.whatsapp_agent?.operator_example_photo_caption ?? '',
+        outbound_call_enabled: tenant?.settings?.whatsapp_agent?.outbound_call_enabled ?? false,
+        outbound_call_phone_number_id: tenant?.settings?.whatsapp_agent?.outbound_call_phone_number_id ?? null,
+        outbound_call_agent_id: tenant?.settings?.whatsapp_agent?.outbound_call_agent_id?.toString() ?? null,
+        sms_notification_enabled: tenant?.settings?.whatsapp_agent?.sms_notification_enabled ?? false,
+        sms_notification_phones: tenant?.settings?.whatsapp_agent?.sms_notification_phones ?? [],
+        ...gcalFields(tenant),
+      };
+    }
+
+    try {
+      const account = await unipileService.getAccountStatus(provider, accountId);
+
+      // Unipile nests status in sources[0].status, not top-level
+      const sources = account.sources as Array<{ id: string; status: string }> | undefined;
+      const sourceStatus = sources?.[0]?.status || '';
+      const topStatus = (account.status as string) || '';
+      const statusStr = (sourceStatus || topStatus).toLowerCase();
+
+      const isConnected = statusStr === 'ok' || statusStr === 'connected';
+      const phone = (account.connection_params as any)?.im?.phone_number || null;
+
+      await Tenant.findByIdAndUpdate(request.user.tenant_id, {
+        $set: {
+          'settings.whatsapp_agent.unipile_account_status': sourceStatus || topStatus,
+          ...(isConnected ? { 'settings.whatsapp_agent.connected_at': new Date() } : {}),
+          ...(phone ? { 'settings.whatsapp_agent.connected_phone': phone } : {}),
+        }
+      });
+
+      // Resolve agent info
+      const agentObjId = tenant?.settings?.whatsapp_agent?.agent_id;
+      const agentDoc = agentObjId ? await Agent.findById(agentObjId).lean() : null;
+
+      return {
+        connected: isConnected,
+        status: sourceStatus || topStatus,
+        account_id: accountId,
+        phone,
+        bridge_provider: provider,
+        agent_id: agentObjId?.toString() || null,
+        agent_name: agentDoc ? `${agentDoc.agent_template} (${agentDoc.phone_number})` : null,
+        agent_active: agentDoc?.is_active ?? false,
+        grace_period_seconds: tenant?.settings?.whatsapp_agent?.grace_period_seconds ?? 180,
+        ai_shift_enabled: tenant?.settings?.whatsapp_agent?.ai_shift_enabled ?? false,
+        ai_shift_schedule: tenant?.settings?.whatsapp_agent?.ai_shift_schedule ?? [],
+        fixed_first_message_enabled: tenant?.settings?.whatsapp_agent?.fixed_first_message_enabled ?? false,
+        fixed_first_message: tenant?.settings?.whatsapp_agent?.fixed_first_message ?? '',
+        operator_workflow_enabled: tenant?.settings?.whatsapp_agent?.operator_workflow_enabled ?? false,
+        operator_phone: tenant?.settings?.whatsapp_agent?.operator_phone ?? null,
+        operator_ref_prefix: tenant?.settings?.whatsapp_agent?.operator_ref_prefix ?? 'R',
+        operator_request_timeout_hours: tenant?.settings?.whatsapp_agent?.operator_request_timeout_hours ?? 24,
+        operator_example_photo_enabled: tenant?.settings?.whatsapp_agent?.operator_example_photo_enabled ?? false,
+        has_example_photo: !!tenant?.settings?.whatsapp_agent?.operator_example_photo_base64,
+        operator_example_photo_base64: tenant?.settings?.whatsapp_agent?.operator_example_photo_base64 ?? null,
+        operator_example_photo_caption: tenant?.settings?.whatsapp_agent?.operator_example_photo_caption ?? '',
+        outbound_call_enabled: tenant?.settings?.whatsapp_agent?.outbound_call_enabled ?? false,
+        outbound_call_phone_number_id: tenant?.settings?.whatsapp_agent?.outbound_call_phone_number_id ?? null,
+        outbound_call_agent_id: tenant?.settings?.whatsapp_agent?.outbound_call_agent_id?.toString() ?? null,
+        sms_notification_enabled: tenant?.settings?.whatsapp_agent?.sms_notification_enabled ?? false,
+        sms_notification_phones: tenant?.settings?.whatsapp_agent?.sms_notification_phones ?? [],
+        ...gcalFields(tenant),
+      };
+    } catch (err) {
+      return {
+        connected: false,
+        status: 'error',
+        error: (err as Error).message,
+        bridge_provider: provider,
+        ai_shift_enabled: tenant?.settings?.whatsapp_agent?.ai_shift_enabled ?? false,
+        ai_shift_schedule: tenant?.settings?.whatsapp_agent?.ai_shift_schedule ?? [],
+        grace_period_seconds: tenant?.settings?.whatsapp_agent?.grace_period_seconds ?? 180,
+        fixed_first_message_enabled: tenant?.settings?.whatsapp_agent?.fixed_first_message_enabled ?? false,
+        fixed_first_message: tenant?.settings?.whatsapp_agent?.fixed_first_message ?? '',
+        operator_workflow_enabled: tenant?.settings?.whatsapp_agent?.operator_workflow_enabled ?? false,
+        operator_phone: tenant?.settings?.whatsapp_agent?.operator_phone ?? null,
+        operator_ref_prefix: tenant?.settings?.whatsapp_agent?.operator_ref_prefix ?? 'R',
+        operator_request_timeout_hours: tenant?.settings?.whatsapp_agent?.operator_request_timeout_hours ?? 24,
+        operator_example_photo_enabled: tenant?.settings?.whatsapp_agent?.operator_example_photo_enabled ?? false,
+        has_example_photo: !!tenant?.settings?.whatsapp_agent?.operator_example_photo_base64,
+        operator_example_photo_base64: tenant?.settings?.whatsapp_agent?.operator_example_photo_base64 ?? null,
+        operator_example_photo_caption: tenant?.settings?.whatsapp_agent?.operator_example_photo_caption ?? '',
+        outbound_call_enabled: tenant?.settings?.whatsapp_agent?.outbound_call_enabled ?? false,
+        outbound_call_phone_number_id: tenant?.settings?.whatsapp_agent?.outbound_call_phone_number_id ?? null,
+        outbound_call_agent_id: tenant?.settings?.whatsapp_agent?.outbound_call_agent_id?.toString() ?? null,
+        sms_notification_enabled: tenant?.settings?.whatsapp_agent?.sms_notification_enabled ?? false,
+        sms_notification_phones: tenant?.settings?.whatsapp_agent?.sms_notification_phones ?? [],
+        ...gcalFields(tenant),
+      };
+    }
+  });
+
+  // POST /whatsapp/disconnect — Disconnect WhatsApp
+  fastify.post('/disconnect', {
+    preHandler: [requireRole('admin')],
+  }, async (request) => {
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    const provider = unipileService.getProviderForTenant(tenant);
+    const accountId = tenant?.settings?.whatsapp_agent?.unipile_account_id;
+
+    if (accountId) {
+      try {
+        await unipileService.disconnectAccount(provider, accountId);
+      } catch (err) {
+        logger.warn('Failed to disconnect account', { provider, error: (err as Error).message });
+      }
+    }
+
+    await Tenant.findByIdAndUpdate(request.user.tenant_id, {
+      $set: {
+        'settings.whatsapp_agent.unipile_account_id': null,
+        'settings.whatsapp_agent.unipile_account_status': null,
+        'settings.whatsapp_agent.connected_at': null,
+        'settings.whatsapp_agent.connected_phone': null,
+      }
+    });
+
+    return { disconnected: true };
+  });
+
+  // PUT /whatsapp/config — Update agent and/or grace_period for WhatsApp AI
+  fastify.put('/config', {
+    preHandler: [requireRole('admin')],
+  }, async (request) => {
+    const {
+      agent_id, profile_agent_id, grace_period_seconds,
+      ai_shift_enabled, ai_shift_schedule,
+      fixed_first_message_enabled, fixed_first_message,
+      operator_workflow_enabled, operator_phone,
+      operator_ref_prefix, operator_request_timeout_hours,
+      operator_example_photo_enabled, operator_example_photo_base64, operator_example_photo_caption,
+      outbound_call_enabled, outbound_call_phone_number_id,
+      outbound_call_agent_id,
+      sms_notification_enabled,
+      sms_notification_phones,
+      google_calendar_appointment_duration_minutes,
+      google_calendar_working_hours,
+      google_calendar_blocked_dates,
+      google_calendar_timezone,
+    } = request.body as {
+      agent_id?: string | null;
+      profile_agent_id?: string | null;
+      grace_period_seconds?: number;
+      ai_shift_enabled?: boolean;
+      ai_shift_schedule?: Array<{ day: number; start: string; end: string }>;
+      fixed_first_message_enabled?: boolean;
+      fixed_first_message?: string;
+      operator_workflow_enabled?: boolean;
+      operator_phone?: string | null;
+      operator_ref_prefix?: string;
+      operator_request_timeout_hours?: number;
+      operator_example_photo_enabled?: boolean;
+      operator_example_photo_base64?: string | null;
+      operator_example_photo_caption?: string;
+      outbound_call_enabled?: boolean;
+      outbound_call_phone_number_id?: string | null;
+      outbound_call_agent_id?: string | null;
+      sms_notification_enabled?: boolean;
+      sms_notification_phones?: string[];
+      google_calendar_appointment_duration_minutes?: number;
+      google_calendar_working_hours?: Array<{ day: number; start: string; end: string }>;
+      google_calendar_blocked_dates?: Array<{ date: string; reason?: string }>;
+      google_calendar_timezone?: string;
+    };
+
+    // Feature-gate checks
+    const tenant = await Tenant.findById(request.user.tenant_id).lean();
+    const enabledFeatures = tenant?.enabled_features ?? [];
+
+    const operatorFields = operator_workflow_enabled !== undefined || operator_phone !== undefined
+      || operator_ref_prefix !== undefined || operator_request_timeout_hours !== undefined
+      || operator_example_photo_enabled !== undefined || operator_example_photo_base64 !== undefined
+      || operator_example_photo_caption !== undefined;
+    if (operatorFields && !enabledFeatures.includes('operator_workflow')) {
+      throw { statusCode: 403, message: 'Operator workflow feature is not enabled for this tenant' };
+    }
+
+    const smsFields = sms_notification_enabled !== undefined || sms_notification_phones !== undefined;
+    if (smsFields && !enabledFeatures.includes('sms_notifications')) {
+      throw { statusCode: 403, message: 'SMS notifications feature is not enabled for this tenant' };
+    }
+
+    const calendarFields = google_calendar_appointment_duration_minutes !== undefined
+      || google_calendar_working_hours !== undefined || google_calendar_blocked_dates !== undefined
+      || google_calendar_timezone !== undefined;
+    if (calendarFields && !enabledFeatures.includes('google_calendar')) {
+      throw { statusCode: 403, message: 'Google Calendar feature is not enabled for this tenant' };
+    }
+
+    const update: Record<string, unknown> = {};
+    if (agent_id !== undefined) {
+      if (agent_id) {
+        // Validate that the agent exists and belongs to this tenant
+        const agent = await Agent.findOne({
+          _id: agent_id,
+          tenant_id: request.user.tenant_id,
+        });
+        if (!agent) {
+          throw { statusCode: 400, message: 'Agent not found or does not belong to this tenant' };
+        }
+        update['settings.whatsapp_agent.agent_id'] = new mongoose.Types.ObjectId(agent_id);
+      } else {
+        update['settings.whatsapp_agent.agent_id'] = null;
+      }
+    }
+    if (profile_agent_id !== undefined) {
+      if (profile_agent_id) {
+        const agent = await Agent.findOne({
+          _id: profile_agent_id,
+          tenant_id: request.user.tenant_id,
+        });
+        if (!agent) {
+          throw { statusCode: 400, message: 'Profile agent not found or does not belong to this tenant' };
+        }
+        update['settings.whatsapp_agent.profile_agent_id'] = new mongoose.Types.ObjectId(profile_agent_id);
+      } else {
+        update['settings.whatsapp_agent.profile_agent_id'] = null;
+      }
+    }
+    if (grace_period_seconds !== undefined) {
+      update['settings.whatsapp_agent.grace_period_seconds'] = Math.max(5, Math.min(1800, grace_period_seconds));
+    }
+    if (ai_shift_enabled !== undefined) {
+      update['settings.whatsapp_agent.ai_shift_enabled'] = !!ai_shift_enabled;
+    }
+    if (ai_shift_schedule !== undefined) {
+      if (!Array.isArray(ai_shift_schedule)) {
+        throw { statusCode: 400, message: 'ai_shift_schedule must be an array' };
+      }
+      for (const entry of ai_shift_schedule) {
+        if (typeof entry.day !== 'number' || entry.day < 0 || entry.day > 6) {
+          throw { statusCode: 400, message: 'Each schedule entry day must be 0-6' };
+        }
+        if (!/^\d{2}:\d{2}$/.test(entry.start) || !/^\d{2}:\d{2}$/.test(entry.end)) {
+          throw { statusCode: 400, message: 'Each schedule entry start/end must be in HH:MM format' };
+        }
+      }
+      update['settings.whatsapp_agent.ai_shift_schedule'] = ai_shift_schedule;
+    }
+    if (fixed_first_message_enabled !== undefined) {
+      update['settings.whatsapp_agent.fixed_first_message_enabled'] = !!fixed_first_message_enabled;
+    }
+    if (fixed_first_message !== undefined) {
+      if (typeof fixed_first_message !== 'string' || fixed_first_message.length > 1000) {
+        throw { statusCode: 400, message: 'fixed_first_message must be a string (max 1000 chars)' };
+      }
+      update['settings.whatsapp_agent.fixed_first_message'] = fixed_first_message;
+    }
+    if (operator_workflow_enabled !== undefined) {
+      update['settings.whatsapp_agent.operator_workflow_enabled'] = !!operator_workflow_enabled;
+    }
+    if (operator_phone !== undefined) {
+      update['settings.whatsapp_agent.operator_phone'] = operator_phone || null;
+    }
+    if (operator_ref_prefix !== undefined) {
+      if (typeof operator_ref_prefix !== 'string' || !/^[A-Z]$/.test(operator_ref_prefix)) {
+        throw { statusCode: 400, message: 'operator_ref_prefix must be a single uppercase letter' };
+      }
+      update['settings.whatsapp_agent.operator_ref_prefix'] = operator_ref_prefix;
+    }
+    if (operator_request_timeout_hours !== undefined) {
+      update['settings.whatsapp_agent.operator_request_timeout_hours'] = Math.max(1, Math.min(168, operator_request_timeout_hours));
+    }
+    if (operator_example_photo_enabled !== undefined) {
+      update['settings.whatsapp_agent.operator_example_photo_enabled'] = !!operator_example_photo_enabled;
+    }
+    if (operator_example_photo_base64 !== undefined) {
+      if (operator_example_photo_base64 && !operator_example_photo_base64.startsWith('data:image/')) {
+        throw { statusCode: 400, message: 'operator_example_photo_base64 must be a data:image/* URL' };
+      }
+      if (operator_example_photo_base64 && operator_example_photo_base64.length > 2_000_000) {
+        throw { statusCode: 400, message: 'Example photo too large (max ~1.5MB)' };
+      }
+      update['settings.whatsapp_agent.operator_example_photo_base64'] = operator_example_photo_base64 || null;
+    }
+    if (operator_example_photo_caption !== undefined) {
+      update['settings.whatsapp_agent.operator_example_photo_caption'] = (operator_example_photo_caption || '').substring(0, 500);
+    }
+    if (outbound_call_enabled !== undefined) {
+      update['settings.whatsapp_agent.outbound_call_enabled'] = !!outbound_call_enabled;
+    }
+    if (outbound_call_phone_number_id !== undefined) {
+      update['settings.whatsapp_agent.outbound_call_phone_number_id'] = outbound_call_phone_number_id || null;
+    }
+    if (outbound_call_agent_id !== undefined) {
+      if (outbound_call_agent_id) {
+        const agent = await Agent.findOne({
+          _id: outbound_call_agent_id,
+          tenant_id: request.user.tenant_id,
+        });
+        if (!agent) {
+          throw { statusCode: 400, message: 'Outbound call agent not found or does not belong to this tenant' };
+        }
+        update['settings.whatsapp_agent.outbound_call_agent_id'] = new mongoose.Types.ObjectId(outbound_call_agent_id);
+      } else {
+        update['settings.whatsapp_agent.outbound_call_agent_id'] = null;
+      }
+    }
+
+    // SMS Notifications
+    if (sms_notification_enabled !== undefined) {
+      update['settings.whatsapp_agent.sms_notification_enabled'] = !!sms_notification_enabled;
+    }
+    if (sms_notification_phones !== undefined) {
+      if (!Array.isArray(sms_notification_phones)) {
+        throw { statusCode: 400, message: 'sms_notification_phones must be an array' };
+      }
+      // Clean phone numbers
+      update['settings.whatsapp_agent.sms_notification_phones'] = sms_notification_phones
+        .map(p => p.replace(/[^0-9]/g, ''))
+        .filter(p => p.length >= 10);
+    }
+
+    // Google Calendar settings
+    if (google_calendar_appointment_duration_minutes !== undefined) {
+      const allowed = [10, 15, 20, 30, 45, 60];
+      if (!allowed.includes(google_calendar_appointment_duration_minutes)) {
+        throw { statusCode: 400, message: 'appointment_duration_minutes must be one of: 10, 15, 20, 30, 45, 60' };
+      }
+      update['settings.whatsapp_agent.google_calendar.appointment_duration_minutes'] = google_calendar_appointment_duration_minutes;
+    }
+    if (google_calendar_working_hours !== undefined) {
+      if (!Array.isArray(google_calendar_working_hours)) {
+        throw { statusCode: 400, message: 'google_calendar_working_hours must be an array' };
+      }
+      for (const entry of google_calendar_working_hours) {
+        if (typeof entry.day !== 'number' || entry.day < 0 || entry.day > 6) {
+          throw { statusCode: 400, message: 'Each working_hours entry day must be 0-6' };
+        }
+        if (!/^\d{2}:\d{2}$/.test(entry.start) || !/^\d{2}:\d{2}$/.test(entry.end)) {
+          throw { statusCode: 400, message: 'Each working_hours entry start/end must be HH:MM' };
+        }
+      }
+      update['settings.whatsapp_agent.google_calendar.working_hours'] = google_calendar_working_hours;
+    }
+    if (google_calendar_blocked_dates !== undefined) {
+      if (!Array.isArray(google_calendar_blocked_dates)) {
+        throw { statusCode: 400, message: 'google_calendar_blocked_dates must be an array' };
+      }
+      for (const entry of google_calendar_blocked_dates) {
+        if (!/^\d{4}-\d{2}-\d{2}$/.test(entry.date)) {
+          throw { statusCode: 400, message: 'Each blocked_dates entry date must be YYYY-MM-DD' };
+        }
+      }
+      update['settings.whatsapp_agent.google_calendar.blocked_dates'] = google_calendar_blocked_dates.map(e => ({
+        date: e.date,
+        reason: e.reason || '',
+      }));
+    }
+    if (google_calendar_timezone !== undefined) {
+      update['settings.whatsapp_agent.google_calendar.timezone'] = google_calendar_timezone;
+    }
+
+    await Tenant.findByIdAndUpdate(request.user.tenant_id, { $set: update });
+    return { updated: true };
+  });
+
+  // ─── Google Calendar ──────────────────────────────────────
+
+  // GET /whatsapp/google-calendar/auth-url — Get OAuth consent URL
+  fastify.get('/google-calendar/auth-url', {
+    preHandler: [requireRole('admin'), requireFeature('google_calendar')],
+  }, async (request) => {
+    const url = googleCalendarService.getAuthUrl(request.user.tenant_id);
+    return { url };
+  });
+
+  // POST /whatsapp/google-calendar/disconnect — Revoke and remove Google Calendar
+  fastify.post('/google-calendar/disconnect', {
+    preHandler: [requireRole('admin'), requireFeature('google_calendar')],
+  }, async (request) => {
+    await googleCalendarService.disconnect(request.user.tenant_id);
+    return { disconnected: true };
+  });
+
+  // GET /whatsapp/google-calendar/calendars — List available calendars
+  fastify.get('/google-calendar/calendars', {
+    preHandler: [requireRole('admin'), requireFeature('google_calendar')],
+  }, async (request) => {
+    const calendars = await googleCalendarService.listCalendars(request.user.tenant_id);
+    return { calendars };
+  });
+
+  // PUT /whatsapp/google-calendar/calendar — Select calendar to use
+  fastify.put('/google-calendar/calendar', {
+    preHandler: [requireRole('admin'), requireFeature('google_calendar')],
+  }, async (request) => {
+    const { calendar_id } = request.body as { calendar_id: string };
+    if (!calendar_id) {
+      throw { statusCode: 400, message: 'calendar_id is required' };
+    }
+    await googleCalendarService.selectCalendar(request.user.tenant_id, calendar_id);
+    return { updated: true };
+  });
+
+  // ─── Appointments ────────────────────────────────────────
+
+  // GET /whatsapp/appointments — Paginated appointment list
+  fastify.get<{
+    Querystring: { page?: string; limit?: string; status?: string; from?: string; to?: string };
+  }>('/appointments', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request) => {
+    const page = Math.max(1, parseInt(request.query.page || '1', 10));
+    const limit = Math.min(parseInt(request.query.limit || '50', 10), 200);
+    const skip = (page - 1) * limit;
+
+    const filter: Record<string, unknown> = { tenant_id: request.user.tenant_id };
+    if (request.query.status === 'scheduled' || request.query.status === 'cancelled') {
+      filter.status = request.query.status;
+    }
+    if (request.query.from || request.query.to) {
+      filter.start_time = {};
+      if (request.query.from) (filter.start_time as Record<string, unknown>).$gte = new Date(request.query.from);
+      if (request.query.to) (filter.start_time as Record<string, unknown>).$lte = new Date(request.query.to);
+    }
+
+    const [appointments, total] = await Promise.all([
+      Appointment.find(filter).sort({ start_time: -1 }).skip(skip).limit(limit).lean(),
+      Appointment.countDocuments(filter),
+    ]);
+
+    return { appointments, total, page, totalPages: Math.ceil(total / limit) };
+  });
+
+  // GET /whatsapp/appointments/:id — Single appointment detail
+  fastify.get<{
+    Params: { id: string };
+  }>('/appointments/:id', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request, reply) => {
+    const appointment = await Appointment.findOne({
+      _id: request.params.id,
+      tenant_id: request.user.tenant_id,
+    }).lean();
+    if (!appointment) {
+      return reply.status(404).send({ error: 'Appointment not found' });
+    }
+    return appointment;
+  });
+
+  // GET /whatsapp/appointments/stats — Analytics summary
+  fastify.get<{
+    Querystring: { from?: string; to?: string };
+  }>('/appointments/stats', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request) => {
+    const tenantId = new mongoose.Types.ObjectId(request.user.tenant_id);
+    const now = new Date();
+    const from = request.query.from ? new Date(request.query.from) : new Date(now.getTime() - 30 * 24 * 60 * 60 * 1000);
+    const to = request.query.to ? new Date(request.query.to) : now;
+
+    const [stats] = await Appointment.aggregate([
+      { $match: { tenant_id: tenantId, start_time: { $gte: from, $lte: to } } },
+      { $facet: {
+        totals: [
+          { $group: {
+            _id: null,
+            total_scheduled: { $sum: { $cond: [{ $eq: ['$status', 'scheduled'] }, 1, 0] } },
+            total_cancelled: { $sum: { $cond: [{ $eq: ['$status', 'cancelled'] }, 1, 0] } },
+          }},
+        ],
+        by_day_of_week: [
+          { $match: { status: 'scheduled' } },
+          { $group: { _id: { $dayOfWeek: '$start_time' }, count: { $sum: 1 } } },
+          { $project: { _id: 0, day: '$_id', count: 1 } },
+          { $sort: { day: 1 } },
+        ],
+        by_hour: [
+          { $match: { status: 'scheduled' } },
+          { $group: { _id: { $hour: '$start_time' }, count: { $sum: 1 } } },
+          { $project: { _id: 0, hour: '$_id', count: 1 } },
+          { $sort: { hour: 1 } },
+        ],
+      }},
+    ]);
+
+    const totals = stats?.totals?.[0] || { total_scheduled: 0, total_cancelled: 0 };
+    const total = totals.total_scheduled + totals.total_cancelled;
+    const upcoming = await Appointment.countDocuments({
+      tenant_id: tenantId,
+      status: 'scheduled',
+      start_time: { $gte: now },
+    });
+
+    return {
+      total_scheduled: totals.total_scheduled,
+      total_cancelled: totals.total_cancelled,
+      cancellation_rate: total > 0 ? Math.round((totals.total_cancelled / total) * 10000) / 100 : 0,
+      by_day_of_week: stats?.by_day_of_week || [],
+      by_hour: stats?.by_hour || [],
+      upcoming,
+    };
+  });
+
+  // GET /whatsapp/agents — List available agents for this tenant (for agent selection dropdown)
+  fastify.get('/agents', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request) => {
+    const agents = await Agent.find({ tenant_id: request.user.tenant_id })
+      .select('_id phone_number agent_template is_active elevenlabs_agent_id')
+      .sort({ is_active: -1, createdAt: -1 })
+      .lean();
+
+    const tenant = await Tenant.findById(request.user.tenant_id).lean();
+    const currentAgentId = tenant?.settings?.whatsapp_agent?.agent_id?.toString() || null;
+
+    return { agents, currentAgentId };
+  });
+
+  // POST /whatsapp/register-webhook — Register webhook for this server
+  fastify.post('/register-webhook', {
+    preHandler: [requireRole('admin')],
+  }, async (request) => {
+    const { webhook_url } = request.body as { webhook_url: string };
+
+    if (!webhook_url?.trim()) {
+      throw { statusCode: 400, message: 'webhook_url is required' };
+    }
+
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    const provider = unipileService.getProviderForTenant(tenant);
+    const result = await unipileService.createWebhook(provider, webhook_url.trim());
+    return { webhook_id: result.id, url: webhook_url, provider };
+  });
+
+  // ─── Blacklist ──────────────────────────────────────────────
+
+  // GET /whatsapp/blacklist — Get blacklisted numbers
+  fastify.get('/blacklist', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request) => {
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    return { numbers: tenant?.settings?.whatsapp_agent?.blacklisted_numbers || [] };
+  });
+
+  // POST /whatsapp/blacklist — Add number to blacklist
+  fastify.post('/blacklist', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { phone } = request.body as { phone: string };
+    const cleaned = phone?.replace(/\s/g, '');
+    if (!cleaned) return reply.status(400).send({ error: 'phone is required' });
+
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    if (!tenant) return reply.status(404).send({ error: 'Tenant not found' });
+
+    const current = tenant.settings?.whatsapp_agent?.blacklisted_numbers || [];
+    if (current.includes(cleaned)) {
+      return { numbers: current };
+    }
+
+    const updated = [...current, cleaned];
+    await Tenant.findByIdAndUpdate(request.user.tenant_id, {
+      $set: { 'settings.whatsapp_agent.blacklisted_numbers': updated }
+    });
+
+    return { numbers: updated };
+  });
+
+  // DELETE /whatsapp/blacklist/:phone — Remove number from blacklist
+  fastify.delete<{ Params: { phone: string } }>('/blacklist/:phone', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request) => {
+    const { phone } = request.params;
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    const current = tenant?.settings?.whatsapp_agent?.blacklisted_numbers || [];
+    const updated = current.filter(n => n !== phone);
+
+    await Tenant.findByIdAndUpdate(request.user.tenant_id, {
+      $set: { 'settings.whatsapp_agent.blacklisted_numbers': updated }
+    });
+
+    return { numbers: updated };
+  });
+
+  // ─── Stats ────────────────────────────────────────────────
+
+  fastify.get('/stats', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request) => {
+    const tenantId = new mongoose.Types.ObjectId(request.user.tenant_id);
+
+    const [totalChats, closedChats, waitingSessions, activeSessions, totalMessages] = await Promise.all([
+      WhatsAppChat.countDocuments({ tenant_id: tenantId }),
+      WhatsAppChat.countDocuments({ tenant_id: tenantId, is_closed: true }),
+      WhatsAppSession.countDocuments({ tenant_id: tenantId, status: 'waiting' }),
+      WhatsAppSession.countDocuments({ tenant_id: tenantId, status: 'active' }),
+      WhatsAppMessage.countDocuments({ tenant_id: tenantId }),
+    ]);
+
+    // Derive AI vs human from active sessions
+    const humanTakeoverCount = await WhatsAppSession.countDocuments({
+      tenant_id: tenantId,
+      status: 'active',
+      $or: [
+        { taken_over_by: { $ne: null } },
+        { taken_over_at: { $ne: null } },
+      ],
+    });
+
+    const aiChats = activeSessions - humanTakeoverCount;
+    const humanChats = humanTakeoverCount + waitingSessions; // waiting = human has first chance
+
+    return {
+      stats: {
+        totalChats,
+        aiChats,
+        humanChats,
+        closedChats,
+        waitingChats: waitingSessions,
+        totalMessages,
+      },
+    };
+  });
+
+  // ─── Chat Management ─────────────────────────────────────
+
+  // GET /whatsapp/chats — List all chats for this tenant
+  fastify.get<{
+    Querystring: { page?: string; limit?: string; mode?: string };
+  }>('/chats', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request) => {
+    const page = parseInt(request.query.page || '1', 10);
+    const limit = Math.min(parseInt(request.query.limit || '20', 10), 100);
+    const skip = (page - 1) * limit;
+    const modeFilter = request.query.mode;
+
+    // For mode filtering, we need to derive mode from sessions
+    if (modeFilter && ['ai', 'human', 'closed'].includes(modeFilter)) {
+      // Use aggregation to filter by derived mode
+      const tenantId = new mongoose.Types.ObjectId(request.user.tenant_id);
+
+      const pipeline: any[] = [
+        { $match: { tenant_id: tenantId, deleted_at: null } },
+        // Left join with active session
+        {
+          $lookup: {
+            from: 'whatsappsessions',
+            let: { sid: '$active_session_id' },
+            pipeline: [
+              { $match: { $expr: { $eq: ['$_id', '$$sid'] } } },
+              { $match: { status: { $ne: 'resolved' } } },
+            ],
+            as: '_session',
+          },
+        },
+        { $addFields: { _activeSession: { $arrayElemAt: ['$_session', 0] } } },
+        // Derive mode
+        {
+          $addFields: {
+            _mode: {
+              $switch: {
+                branches: [
+                  // No active session + is_closed
+                  {
+                    case: { $and: [{ $eq: [{ $ifNull: ['$_activeSession', null] }, null] }, { $eq: ['$is_closed', true] }] },
+                    then: 'closed',
+                  },
+                  // No active session + not closed
+                  {
+                    case: { $eq: [{ $ifNull: ['$_activeSession', null] }, null] },
+                    then: 'ai',
+                  },
+                  // Session waiting
+                  {
+                    case: { $eq: ['$_activeSession.status', 'waiting'] },
+                    then: 'human',
+                  },
+                  // Session active + taken over
+                  {
+                    case: {
+                      $and: [
+                        { $eq: ['$_activeSession.status', 'active'] },
+                        {
+                          $or: [
+                            { $ne: [{ $ifNull: ['$_activeSession.taken_over_by', null] }, null] },
+                            { $ne: [{ $ifNull: ['$_activeSession.taken_over_at', null] }, null] },
+                          ],
+                        },
+                      ],
+                    },
+                    then: 'human',
+                  },
+                  // Session active + no takeover
+                  {
+                    case: { $eq: ['$_activeSession.status', 'active'] },
+                    then: 'ai',
+                  },
+                ],
+                default: 'ai',
+              },
+            },
+          },
+        },
+        { $match: { _mode: modeFilter } },
+        { $sort: { last_message_at: -1 as const } },
+        {
+          $facet: {
+            data: [{ $skip: skip }, { $limit: limit }],
+            count: [{ $count: 'total' }],
+          },
+        },
+      ];
+
+      const [result] = await WhatsAppChat.aggregate(pipeline);
+      const rawChats = result?.data || [];
+      const total = result?.count?.[0]?.total || 0;
+      const chats = await enrichChats(rawChats);
+
+      return { chats, total, page, totalPages: Math.ceil(total / limit) };
+    }
+
+    // No mode filter — simple query
+    const filter: Record<string, unknown> = { tenant_id: request.user.tenant_id, deleted_at: null };
+
+    const [rawChats, total] = await Promise.all([
+      WhatsAppChat.find(filter)
+        .sort({ last_message_at: -1 })
+        .skip(skip)
+        .limit(limit)
+        .lean(),
+      WhatsAppChat.countDocuments(filter),
+    ]);
+
+    const chats = await enrichChats(rawChats);
+    return { chats, total, page, totalPages: Math.ceil(total / limit) };
+  });
+
+  // GET /whatsapp/chats/:chatId — Get single chat detail
+  fastify.get<{ Params: { chatId: string } }>('/chats/:chatId', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const rawChat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    }).lean();
+
+    if (!rawChat) return reply.status(404).send({ error: 'Chat not found' });
+
+    const chat = await enrichChat(rawChat);
+
+    // Include contact profile if linked
+    if (rawChat.contact_profile_id) {
+      chat.contact_profile = await WhatsAppContactProfile.findById(rawChat.contact_profile_id).lean();
+    }
+
+    return { chat };
+  });
+
+  // GET /whatsapp/chats/:chatId/messages — Get messages for a chat
+  fastify.get<{
+    Params: { chatId: string };
+    Querystring: { page?: string; limit?: string };
+  }>('/chats/:chatId/messages', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const page = parseInt(request.query.page || '1', 10);
+    const limit = Math.min(parseInt(request.query.limit || '50', 10), 200);
+    const skip = (page - 1) * limit;
+
+    // Verify chat belongs to tenant
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    const [messages, total] = await Promise.all([
+      WhatsAppMessage.find({ chat_id: chatId })
+        .sort({ createdAt: 1 })
+        .skip(skip)
+        .limit(limit)
+        .lean(),
+      WhatsAppMessage.countDocuments({ chat_id: chatId }),
+    ]);
+
+    return { messages, total, page, totalPages: Math.ceil(total / limit) };
+  });
+
+  // GET /whatsapp/chats/:chatId/sessions — Get session history for a chat
+  fastify.get<{
+    Params: { chatId: string };
+    Querystring: { page?: string; limit?: string };
+  }>('/chats/:chatId/sessions', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const page = parseInt(request.query.page || '1', 10);
+    const limit = Math.min(parseInt(request.query.limit || '20', 10), 50);
+    const skip = (page - 1) * limit;
+
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    const [sessions, total] = await Promise.all([
+      WhatsAppSession.find({ chat_id: chatId })
+        .populate('taken_over_by', 'name email')
+        .sort({ started_at: -1 })
+        .skip(skip)
+        .limit(limit)
+        .lean(),
+      WhatsAppSession.countDocuments({ chat_id: chatId }),
+    ]);
+
+    return { sessions, total, page, totalPages: Math.ceil(total / limit) };
+  });
+
+  // ─── Takeover / Release / Close / Reopen ──────────────────
+
+  // POST /whatsapp/chats/:chatId/takeover
+  fastify.post<{ Params: { chatId: string } }>('/chats/:chatId/takeover', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    // Look up active session
+    const session = chat.active_session_id
+      ? await WhatsAppSession.findById(chat.active_session_id)
+      : null;
+
+    if (!session || session.status === 'resolved') {
+      return reply.status(400).send({ error: 'No active session to take over' });
+    }
+
+    // If session is waiting, cancel the grace timer
+    if (session.status === 'waiting') {
+      whatsappAgentService.cancelSession(session._id.toString());
+      session.status = 'active';
+    }
+
+    // Close the ElevenLabs WebSocket
+    whatsappAgentService.closeConnection(chat.unipile_chat_id);
+
+    session.taken_over_by = new mongoose.Types.ObjectId(request.user.id);
+    session.taken_over_at = new Date();
+    await session.save();
+
+    const enriched = await enrichChat(chat);
+    return { chat: enriched };
+  });
+
+  // POST /whatsapp/chats/:chatId/release
+  fastify.post<{ Params: { chatId: string } }>('/chats/:chatId/release', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const { immediate } = (request.body as { immediate?: boolean }) || {};
+
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    // Look up active session
+    const session = chat.active_session_id
+      ? await WhatsAppSession.findById(chat.active_session_id)
+      : null;
+
+    if (!session || session.status === 'resolved') {
+      return reply.status(400).send({ error: 'No active session to release' });
+    }
+
+    // Verify it's in human mode (taken over)
+    if (!session.taken_over_by && !session.taken_over_at) {
+      return reply.status(400).send({ error: 'Chat is not in human mode' });
+    }
+
+    // Clear human takeover, reset EL fields so a new conversation starts
+    session.taken_over_by = null;
+    session.taken_over_at = null;
+    session.elevenlabs_conversation_id = null;
+    session.elevenlabs_conversation_created_at = null;
+    session.elevenlabs_last_interaction_at = null;
+    await session.save();
+
+    let pendingCount = 0;
+
+    if (immediate) {
+      const tenant = await Tenant.findById(request.user.tenant_id).lean();
+      const agentObjId = tenant?.settings?.whatsapp_agent?.agent_id;
+      const agentDoc = agentObjId ? await Agent.findById(agentObjId).lean() : null;
+      const agentId = (agentDoc && agentDoc.is_active) ? agentDoc.elevenlabs_agent_id : null;
+
+      if (agentId) {
+        const result = await whatsappAgentService.replayPendingMessages({
+          tenantId: request.user.tenant_id,
+          agentId,
+          session,
+        });
+        pendingCount = result.pendingCount;
+      } else {
+        logger.warn('Immediate AI response requested but no agent configured', { chatId });
+      }
+    }
+
+    const enriched = await enrichChat(chat);
+    return { chat: enriched, pendingCount };
+  });
+
+  // POST /whatsapp/chats/:chatId/close
+  fastify.post<{ Params: { chatId: string } }>('/chats/:chatId/close', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    // Resolve active session if any
+    let resolvedSessionId: string | null = null;
+    if (chat.active_session_id) {
+      const session = await WhatsAppSession.findById(chat.active_session_id);
+      if (session && session.status !== 'resolved') {
+        if (session.status === 'waiting') {
+          whatsappAgentService.cancelSession(session._id.toString());
+        }
+        session.status = 'resolved';
+        session.resolved_by = 'manual';
+        session.resolved_at = new Date();
+        await session.save();
+        resolvedSessionId = session._id.toString();
+      }
+      chat.active_session_id = null;
+    }
+
+    whatsappAgentService.closeConnection(chat.unipile_chat_id);
+
+    chat.is_closed = true;
+    await chat.save();
+
+    if (resolvedSessionId) {
+      whatsappAgentService.updateContactProfileSummary(resolvedSessionId).catch(err => {
+        logger.error('Profile summary update failed after close', { error: (err as Error).message });
+      });
+      whatsappAgentService.generateSessionLabels(resolvedSessionId).catch(err => {
+        logger.error('Session labelling failed after close', { error: (err as Error).message });
+      });
+    }
+
+    const enriched = await enrichChat(chat);
+    return { chat: enriched };
+  });
+
+  // POST /whatsapp/chats/:chatId/reopen
+  fastify.post<{ Params: { chatId: string } }>('/chats/:chatId/reopen', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    chat.is_closed = false;
+    await chat.save();
+
+    const enriched = await enrichChat(chat);
+    return { chat: enriched };
+  });
+
+  // DELETE /whatsapp/chats/:chatId — Soft-delete a chat (hidden until contact messages again)
+  fastify.delete<{ Params: { chatId: string } }>('/chats/:chatId', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    // Resolve active session if any
+    let deletedSessionId: string | null = null;
+    if (chat.active_session_id) {
+      const session = await WhatsAppSession.findById(chat.active_session_id);
+      if (session && session.status !== 'resolved') {
+        session.status = 'resolved';
+        session.resolved_by = 'manual';
+        session.resolved_at = new Date();
+        await session.save();
+        whatsappAgentService.cancelSession(session._id.toString());
+        deletedSessionId = session._id.toString();
+      }
+      chat.active_session_id = null;
+    }
+
+    // Close EL WebSocket if connected
+    whatsappAgentService.closeConnection(chat.unipile_chat_id);
+
+    chat.is_closed = true;
+    chat.deleted_at = new Date();
+    await chat.save();
+
+    if (deletedSessionId) {
+      whatsappAgentService.updateContactProfileSummary(deletedSessionId).catch(err => {
+        logger.error('Profile summary update failed after delete', { error: (err as Error).message });
+      });
+      whatsappAgentService.generateSessionLabels(deletedSessionId).catch(err => {
+        logger.error('Session labelling failed after delete', { error: (err as Error).message });
+      });
+    }
+
+    return { success: true };
+  });
+
+  // ─── Manual Message ───────────────────────────────────────
+
+  // POST /whatsapp/chats/:chatId/send
+  fastify.post<{ Params: { chatId: string } }>('/chats/:chatId/send', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const { text } = request.body as { text: string };
+
+    if (!text?.trim()) {
+      return reply.status(400).send({ error: 'Message text is required' });
+    }
+
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    // Verify chat is in human mode (has an active session with takeover)
+    const session = chat.active_session_id
+      ? await WhatsAppSession.findById(chat.active_session_id)
+      : null;
+
+    const isHumanMode = session
+      && session.status !== 'resolved'
+      && (session.taken_over_by || session.taken_over_at || session.status === 'waiting');
+
+    if (!isHumanMode) {
+      return reply.status(400).send({ error: 'Chat must be in human mode to send manual messages' });
+    }
+
+    // If session was waiting, the human is now responding — cancel grace timer and resolve
+    if (session!.status === 'waiting') {
+      whatsappAgentService.cancelSession(session!._id.toString());
+      session!.status = 'resolved';
+      session!.resolved_by = 'human';
+      session!.resolved_at = new Date();
+      await session!.save();
+      chat.active_session_id = null;
+      await chat.save();
+
+      whatsappAgentService.updateContactProfileSummary(session!._id.toString()).catch(err => {
+        logger.error('Profile summary update failed after send', { error: (err as Error).message });
+      });
+      whatsappAgentService.generateSessionLabels(session!._id.toString()).catch(err => {
+        logger.error('Session labelling failed after send', { error: (err as Error).message });
+      });
+    }
+
+    // Send via bridge provider
+    const tenant = await Tenant.findById(request.user.tenant_id);
+    const provider = unipileService.getProviderForTenant(tenant);
+    const result = await unipileService.sendMessage(provider, chat.unipile_chat_id, text.trim());
+
+    // Store in DB
+    const message = await WhatsAppMessage.create({
+      chat_id: chat._id,
+      session_id: session!._id,
+      tenant_id: chat.tenant_id,
+      unipile_message_id: result.message_id || null,
+      sender: 'human',
+      sender_name: request.user.id,
+      text: text.trim(),
+      sent_via_unipile: true,
+    });
+
+    // Update chat
+    chat.last_message_at = new Date();
+    chat.last_message_preview = text.trim().substring(0, 100);
+    chat.message_count += 1;
+    await chat.save();
+
+    return { message: message.toObject() };
+  });
+
+  // ─── Contact Profiles ──────────────────────────────────────
+
+  // GET /whatsapp/contacts — List contact profiles
+  fastify.get<{
+    Querystring: { page?: string; limit?: string; search?: string };
+  }>('/contacts', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request) => {
+    const page = parseInt(request.query.page || '1', 10);
+    const limit = Math.min(parseInt(request.query.limit || '20', 10), 100);
+    const skip = (page - 1) * limit;
+    const search = request.query.search?.trim();
+
+    const filter: Record<string, unknown> = { tenant_id: request.user.tenant_id };
+    if (search) {
+      filter.$or = [
+        { display_name: { $regex: search, $options: 'i' } },
+        { phone: { $regex: search, $options: 'i' } },
+        { tags: { $in: [new RegExp(search, 'i')] } },
+      ];
+    }
+
+    const [profiles, total] = await Promise.all([
+      WhatsAppContactProfile.find(filter)
+        .sort({ last_seen_at: -1 })
+        .skip(skip)
+        .limit(limit)
+        .lean(),
+      WhatsAppContactProfile.countDocuments(filter),
+    ]);
+
+    return { profiles, total, page, totalPages: Math.ceil(total / limit) };
+  });
+
+  // GET /whatsapp/contacts/:profileId — Get single profile with linked chats
+  fastify.get<{ Params: { profileId: string } }>('/contacts/:profileId', {
+    preHandler: [requireRole('admin', 'manager', 'viewer')],
+  }, async (request, reply) => {
+    const profile = await WhatsAppContactProfile.findOne({
+      _id: request.params.profileId,
+      tenant_id: request.user.tenant_id,
+    }).lean();
+
+    if (!profile) return reply.status(404).send({ error: 'Profile not found' });
+
+    const chats = await WhatsAppChat.find({
+      tenant_id: request.user.tenant_id,
+      contact_phone: profile.phone,
+      deleted_at: null,
+    }).sort({ last_message_at: -1 }).lean();
+
+    return { profile, chats };
+  });
+
+  // PUT /whatsapp/contacts/:profileId — Update profile notes/tags
+  fastify.put<{ Params: { profileId: string } }>('/contacts/:profileId', {
+    preHandler: [requireRole('admin', 'manager')],
+  }, async (request, reply) => {
+    const { notes, tags } = request.body as { notes?: string; tags?: string[] };
+
+    const update: Record<string, unknown> = {};
+    if (notes !== undefined) update.notes = notes;
+    if (tags !== undefined) update.tags = tags;
+
+    const profile = await WhatsAppContactProfile.findOneAndUpdate(
+      { _id: request.params.profileId, tenant_id: request.user.tenant_id },
+      { $set: update },
+      { new: true },
+    );
+
+    if (!profile) return reply.status(404).send({ error: 'Profile not found' });
+    return { profile };
+  });
+
+  // POST /whatsapp/chats/:chatId/generate-summary — Manually trigger profile summary for a chat's latest session
+  fastify.post<{ Params: { chatId: string } }>('/chats/:chatId/generate-summary', {
+    preHandler: [requireRole('admin')],
+  }, async (request, reply) => {
+    const { chatId } = request.params;
+    const chat = await WhatsAppChat.findOne({
+      _id: chatId,
+      tenant_id: request.user.tenant_id,
+    });
+    if (!chat) return reply.status(404).send({ error: 'Chat not found' });
+
+    // Ensure a contact profile exists — auto-create from chat data if missing
+    if (!chat.contact_profile_id) {
+      const profile = await WhatsAppContactProfile.findOneAndUpdate(
+        { tenant_id: chat.tenant_id, phone: chat.contact_phone },
+        {
+          $set: { display_name: chat.contact_name, last_seen_at: new Date() },
+          $setOnInsert: { first_seen_at: new Date(), notes: '', tags: [], ai_summary: '', metadata: {} },
+        },
+        { upsert: true, new: true },
+      );
+      chat.contact_profile_id = profile._id;
+      await WhatsAppChat.updateOne({ _id: chat._id }, { $set: { contact_profile_id: profile._id } });
+    }
+
+    // Find the latest session with messages
+    const latestSession = await WhatsAppSession.findOne({ chat_id: chatId })
+      .sort({ started_at: -1 })
+      .lean();
+
+    if (!latestSession) {
+      return reply.status(400).send({ error: 'No sessions found for this chat' });
+    }
+
+    const messageCount = await WhatsAppMessage.countDocuments({ session_id: latestSession._id });
+    if (messageCount < 2) {
+      return reply.status(400).send({ error: 'Session has fewer than 2 messages' });
+    }
+
+    // Run synchronously so we can return the result
+    try {
+      await whatsappAgentService.updateContactProfileSummary(latestSession._id.toString());
+    } catch (err) {
+      return reply.status(500).send({ error: (err as Error).message });
+    }
+
+    // Return updated profile
+    const profile = await WhatsAppContactProfile.findById(chat.contact_profile_id).lean();
+
+    return {
+      session_id: latestSession._id,
+      session_message_count: messageCount,
+      profile,
+    };
+  });
+}