elevenlabs-webhook-nodejs 1.0.0

package/src/modules/webhooks/unipile.routes.ts

@@ -0,0 +1,917 @@
+import type { FastifyInstance, FastifyRequest, FastifyReply } from 'fastify';
+import mongoose from 'mongoose';
+import config from '../../config';
+import logger from '../../utils/logger';
+import Tenant from '../tenants/tenant.model';
+import Agent from '../agents/agent.model';
+import WhatsAppChat from '../whatsapp/whatsapp-chat.model';
+import WhatsAppSession from '../whatsapp/whatsapp-session.model';
+import WhatsAppMessage from '../whatsapp/whatsapp-message.model';
+import WhatsAppContactProfile from '../whatsapp/whatsapp-contact-profile.model';
+import whatsappAgentService from '../../services/whatsapp-agent.service';
+import unipileService from '../../services/unipile.service';
+import elevenlabsService from '../../services/elevenlabs.service';
+import OperatorRequest from '../whatsapp/operator-request.model';
+import SttUsage from '../whatsapp/stt-usage.model';
+
+interface UnipileWebhookPayload {
+  account_id: string;
+  account_type: string;
+  event: string;
+  chat_id: string;
+  message_id: string;
+  message: string;
+  content_type?: string;
+  timestamp: string;
+  is_sender: boolean;
+  is_event?: boolean;
+  event_type?: number;
+  hidden?: boolean;
+  sender: {
+    attendee_id: string;
+    attendee_name: string;
+    attendee_provider_id: string;
+    attendee_specifics?: { phone_number?: string };
+  };
+  attendees: Array<{
+    attendee_id: string;
+    attendee_name: string;
+    attendee_provider_id: string;
+    attendee_specifics?: { phone_number?: string };
+  }>;
+  account_info: {
+    type: string;
+    phone_number?: string;
+    [key: string]: unknown;
+  };
+  ad_context?: {
+    ad?: { title?: string | null; body?: string | null; source_url?: string | null };
+    source?: string;
+    app?: string;
+  } | null;
+  quoted_text?: string | null;
+}
+
+export default async function unipileWebhookRoutes(fastify: FastifyInstance): Promise<void> {
+  // Accept any content type Unipile might send
+  fastify.addContentTypeParser('*', { parseAs: 'string' }, (_request, payload, done) => {
+    try {
+      done(null, JSON.parse(payload as string));
+    } catch {
+      done(null, payload);
+    }
+  });
+
+  fastify.post('/', async (request: FastifyRequest, reply: FastifyReply) => {
+    // Validate shared secret — accept if it matches either provider's secret
+    const secret = request.headers['x-unipile-secret'] as string;
+    if (secret) {
+      const validSecrets = [config.unipile.webhookSecret, config.baileys.webhookSecret].filter(Boolean);
+      if (validSecrets.length > 0 && !validSecrets.includes(secret)) {
+        logger.warn('Invalid webhook secret');
+        return reply.status(401).send({ error: 'Invalid secret' });
+      }
+    }
+
+    const payload = request.body as UnipileWebhookPayload;
+
+    // Respond immediately
+    reply.status(200).send({ status: 'received' });
+
+    // Process in background
+    processUnipileWebhook(payload).catch(error => {
+      logger.error('Unipile webhook processing failed', {
+        error: (error as Error).message,
+        stack: (error as Error).stack,
+      });
+    });
+  });
+}
+
+function isValidPhoneNumber(phone: string): boolean {
+  return /^\+?\d{10,15}$/.test(phone.replace(/[\s\-()]/g, ''));
+}
+
+/**
+ * Create a new WhatsAppSession for a chat and link it.
+ */
+async function createSession(
+  chat: InstanceType<typeof WhatsAppChat>,
+  tenantId: string,
+  gracePeriodSeconds: number,
+): Promise<InstanceType<typeof WhatsAppSession>> {
+  const deadline = new Date(Date.now() + gracePeriodSeconds * 1000);
+  const session = await WhatsAppSession.create({
+    chat_id: chat._id,
+    tenant_id: tenantId,
+    status: 'waiting',
+    grace_deadline: deadline,
+    started_at: new Date(),
+  });
+
+  chat.active_session_id = session._id;
+  if (chat.is_closed) chat.is_closed = false;
+  if (chat.deleted_at) chat.deleted_at = null;
+  await chat.save();
+
+  // Increment profile session count
+  if (chat.contact_profile_id) {
+    await WhatsAppContactProfile.updateOne(
+      { _id: chat.contact_profile_id },
+      { $inc: { total_sessions: 1 } },
+    );
+  }
+
+  return session;
+}
+
+const UNIPILE_MEDIA_PLACEHOLDER = '-- Unipile cannot display this type of message yet';
+const FRIENDLY_MEDIA_TEXT = 'Bu mesajı görüntülemek için WhatsApp uygulamasını kontrol edin';
+
+async function processUnipileWebhook(payload: UnipileWebhookPayload): Promise<void> {
+  logger.info('Unipile webhook payload', { payload: JSON.stringify(payload).substring(0, 1000) });
+
+  // Only handle message_received events
+  if (payload.event !== 'message_received') {
+    logger.debug('Skipping non-message Unipile event', { event: payload.event });
+    return;
+  }
+
+  // Only handle WhatsApp
+  if (payload.account_type !== 'WHATSAPP') {
+    logger.debug('Skipping non-WhatsApp Unipile event', { type: payload.account_type });
+    return;
+  }
+
+  // Skip empty messages
+  if (!payload.message?.trim()) {
+    logger.debug('Ignoring empty message');
+    return;
+  }
+
+  // ─── System message detection (two layers) ───────────────
+  // Layer 1: Unipile structural fields (most reliable)
+  // Layer 2: Text pattern fallback (for event_type=0 / unsupported events)
+  // System messages are stored for visibility but never trigger AI or sessions.
+
+  const SYSTEM_MESSAGE_PATTERNS = [
+    // EN — Voice/video calls
+    /^(incoming|missed|declined|unanswered|group) (voice|video) call/i,
+    /^voice call(,| ended| answered)/i,
+    /^video call(,| ended| answered)/i,
+    // TR — Voice/video calls
+    /^(gelen|cevaps[ıi]z|reddedilen|cevaplanmayan|grup) (sesli|g[öo]r[üu]nt[üu]l[üu]) arama/i,
+    /^sesli arama (sona erdi|cevapland)/i,
+    /^g[öo]r[üu]nt[üu]l[üu] arama (sona erdi|cevapland)/i,
+
+    // EN — Message deletion
+    /^this message was deleted/i,
+    /^you deleted this message/i,
+    // TR — Message deletion
+    /^bu mesaj silindi/i,
+    /^bu mesaj[ıi] sildiniz/i,
+    /taraf[ıi]ndan silindi/i,
+
+    // EN — Encryption & security
+    /^messages and calls are end-to-end encrypted/i,
+    /security code.*(changed|verified)/i,
+    // TR — Encryption & security
+    /mesajlar ve aramalar u[çc]tan u[çc]a [şs]ifrelidir/i,
+    /g[üu]venlik kodu.* de[gğ]i[şs]ti/i,
+
+    // EN — Disappearing messages
+    /turned (on|off) disappearing messages/i,
+    /disappearing messages are (on|off)/i,
+    // TR — Disappearing messages
+    /s[üu]reli mesajlar[ıi] (a[çc]t|kapatt)/i,
+    /s[üu]reli mesajlar (a[çc][ıi]k|kapal[ıi])/i,
+
+    // EN — Waiting / pending
+    /^waiting for this message/i,
+    // TR — Waiting / pending
+    /^bu mesaj bekleniyor/i,
+
+    // EN — Live location
+    /is sharing live location/i,
+    /stopped sharing live location/i,
+    // TR — Live location
+    /canl[ıi] konum payla[şs]/i,
+
+    // EN — Payment
+    /^payment (sent|received)/i,
+    /^payment request (sent|received)/i,
+    // TR — Payment
+    /^[öo]deme (g[öo]nderildi|al[ıi]nd[ıi])/i,
+    /^[öo]deme iste[gğ]i (g[öo]nderildi|al[ıi]nd[ıi])/i,
+
+    // EN — Business account
+    /this chat is with a business account/i,
+    /uses a secure service from Meta/i,
+    // TR — Business account
+    /bu sohbet bir i[şs]letme hesab[ıi]yla/i,
+
+    // EN — Group management
+    /^you were (added|removed)/i,
+    /^you('re| are) now an admin/i,
+    /^you('re| are) no longer an admin/i,
+    /is now an admin$/i,
+    /is no longer an admin$/i,
+    /joined using this group's invite link/i,
+    /pinned a message$/i,
+    /unpinned a message$/i,
+    /changed the (subject|group description)/i,
+    /changed this group's icon/i,
+    /only admins can (send messages|edit)/i,
+    /all participants can (send messages|edit)/i,
+    // TR — Group management
+    /art[ıi]k bir y[öo]netici/i,
+    /art[ıi]k y[öo]netici de[gğ]il/i,
+    /grubun davet ba[gğ]lant[ıi]s[ıi]n[ıi] kullanarak kat[ıi]ld[ıi]/i,
+    /bir mesaj[ıi] sabitledi/i,
+    /sabitlenen mesaj[ıi] kald[ıi]rd[ıi]/i,
+
+    // EN — View once
+    /sent a view once (message|photo|video)/i,
+    // TR — View once
+    /bir kez g[öo]r[üu]nt[üu]lenen (mesaj|foto|video)/i,
+
+    // EN — Old version
+    /using an old(er)? version of WhatsApp/i,
+    /need(s)? to update WhatsApp/i,
+  ];
+
+  const trimmedMessage = payload.message.trim();
+  const isSystemMessage =
+    payload.is_event === true ||
+    payload.hidden === true ||
+    SYSTEM_MESSAGE_PATTERNS.some(pattern => pattern.test(trimmedMessage));
+
+  if (isSystemMessage) {
+    logger.info('System message detected — AI will be skipped', {
+      chat_id: payload.chat_id,
+      message: trimmedMessage.substring(0, 80),
+      is_event: payload.is_event,
+      event_type: payload.event_type,
+      hidden: payload.hidden,
+    });
+  }
+
+  // Detect Unipile media placeholder and replace with friendly text.
+  // Baileys now sends descriptive labels like "[Kullanıcı fotoğraf gönderdi]"
+  // which pass through to the AI. Only the legacy generic placeholder gets replaced.
+  const isLegacyMediaPlaceholder = payload.message === UNIPILE_MEDIA_PLACEHOLDER;
+  if (isLegacyMediaPlaceholder) {
+    payload.message = FRIENDLY_MEDIA_TEXT;
+  }
+
+  // Find tenant by unipile_account_id
+  const tenant = await Tenant.findOne({
+    'settings.whatsapp_agent.unipile_account_id': payload.account_id,
+    enabled_features: 'whatsapp_agent',
+  });
+
+  if (!tenant) {
+    logger.warn('No tenant found for Unipile account', { account_id: payload.account_id });
+    return;
+  }
+
+  // ─── Voice message transcription (STT) ──────────────────────
+  if (
+    payload.content_type === 'audioMessage' &&
+    !payload.is_sender &&
+    tenant.enabled_features.includes('voice_transcription') &&
+    payload.message_id
+  ) {
+    try {
+      const provider = unipileService.getProviderForTenant(tenant);
+      const { audio_base64 } = await unipileService.downloadAudio(provider, payload.chat_id, payload.message_id);
+      const audioBuffer = Buffer.from(audio_base64, 'base64');
+      const { text: transcript, durationSeconds, detectedLanguage } = await elevenlabsService.speechToText(audioBuffer);
+      if (transcript.trim()) {
+        payload.message = transcript;
+        payload.content_type = 'transcribedAudio';
+        logger.info('Voice message transcribed', {
+          chatId: payload.chat_id,
+          transcriptLength: transcript.length,
+          durationSeconds,
+          detectedLanguage,
+          preview: transcript.substring(0, 100),
+        });
+
+        // Log STT usage
+        SttUsage.create({
+          tenant_id: tenant._id,
+          chat_id: payload.chat_id,
+          message_id: payload.message_id,
+          duration_seconds: durationSeconds,
+          character_count: transcript.length,
+          language: detectedLanguage,
+        }).catch(() => {});
+      }
+    } catch (err) {
+      logger.error('Voice message transcription failed, using label fallback', {
+        chatId: payload.chat_id,
+        error: (err as Error).message,
+      });
+    }
+  }
+
+  // ─── Operator / forwarding reply detection ──────────────────
+  // Check for REF code from operator_phone or conversation_forwarding_phone
+  const operatorSettings = tenant.settings?.whatsapp_agent;
+  const knownOperatorPhones: string[] = [];
+  if (operatorSettings?.operator_workflow_enabled && operatorSettings.operator_phone) {
+    knownOperatorPhones.push(operatorSettings.operator_phone.replace(/[^0-9]/g, ''));
+  }
+  if (tenant.enabled_features.includes('conversation_forwarding') && operatorSettings?.conversation_forwarding_phone) {
+    const cfPhone = operatorSettings.conversation_forwarding_phone.replace(/[^0-9]/g, '');
+    if (!knownOperatorPhones.includes(cfPhone)) knownOperatorPhones.push(cfPhone);
+  }
+
+  if (knownOperatorPhones.length > 0) {
+    // Check for REF code in the message text OR in the quoted (replied-to) message
+    const refMatch = payload.message.trim().match(/\b([A-Z]-[A-Z0-9]{4})\b/)
+      || (payload.quoted_text?.match(/\b([A-Z]-[A-Z0-9]{4})\b/) ?? null);
+
+    if (refMatch) {
+      // Scenario 1: incoming message from a known operator/forwarding phone
+      if (!payload.is_sender) {
+        const senderPhone = payload.attendees?.[0]?.attendee_specifics?.phone_number
+          || payload.attendees?.[0]?.attendee_provider_id || '';
+        const normalizedSender = senderPhone.replace(/[^0-9]/g, '');
+
+        if (normalizedSender && knownOperatorPhones.includes(normalizedSender)) {
+          logger.info('Operator message detected (incoming)', { phone: senderPhone, message: payload.message.substring(0, 100) });
+          await handleOperatorReply(tenant, payload);
+          return;
+        }
+      }
+
+      // Scenario 2: self-sent message containing a REF code (operator uses same device)
+      if (payload.is_sender) {
+        // Verify this REF code exists and is pending or recently responded (for follow-up documents)
+        const pendingRequest = await OperatorRequest.findOne({
+          ref_code: refMatch[1],
+          tenant_id: tenant._id,
+          status: { $in: ['pending', 'responded'] },
+        });
+        if (pendingRequest) {
+          logger.info('Operator message detected (self-sent)', { refCode: refMatch[1], message: payload.message.substring(0, 100) });
+          await handleOperatorReply(tenant, payload);
+          return;
+        }
+      }
+    }
+  }
+
+  // Determine contact info from the other party (attendees[0] is always the contact)
+  const contact = payload.attendees?.[0];
+  const contactName = contact?.attendee_name || 'Bilinmiyor';
+  const contactPhone = contact?.attendee_specifics?.phone_number
+    || contact?.attendee_provider_id || '';
+
+  // Filter out group chats — only process valid phone numbers
+  if (!isValidPhoneNumber(contactPhone)) {
+    logger.debug('Ignoring non-phone chat (group?)', { chat_id: payload.chat_id, contactPhone });
+    return;
+  }
+
+  // Upsert contact profile
+  const profile = await WhatsAppContactProfile.findOneAndUpdate(
+    { tenant_id: tenant._id, phone: contactPhone },
+    {
+      $set: { display_name: contactName, last_seen_at: new Date() },
+      $setOnInsert: { first_seen_at: new Date(), notes: '', tags: [], ai_summary: '', metadata: {} },
+    },
+    { upsert: true, new: true },
+  );
+
+  const gracePeriodSeconds = tenant.settings?.whatsapp_agent?.grace_period_seconds ?? 180;
+  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 : '';
+  const blacklist = tenant.settings?.whatsapp_agent?.blacklisted_numbers || [];
+  const isBlacklisted = blacklist.includes(contactPhone);
+  const skipAI = isBlacklisted || isSystemMessage || isLegacyMediaPlaceholder;
+
+  // Find or create WhatsAppChat
+  let chat = await WhatsAppChat.findOne({ unipile_chat_id: payload.chat_id });
+
+  // If not found by chat_id, try matching by phone (handles provider migration)
+  if (!chat && contactPhone) {
+    chat = await WhatsAppChat.findOne({ tenant_id: tenant._id, contact_phone: contactPhone, deleted_at: null });
+    if (chat) {
+      const oldChatId = chat.unipile_chat_id;
+      chat.unipile_chat_id = payload.chat_id;
+      chat.unipile_account_id = payload.account_id;
+
+      // Clear stale session from previous provider
+      if (chat.active_session_id) {
+        const staleSession = await WhatsAppSession.findById(chat.active_session_id);
+        if (staleSession && staleSession.status !== 'resolved') {
+          staleSession.status = 'resolved';
+          staleSession.resolved_at = new Date();
+          await staleSession.save();
+        }
+        chat.active_session_id = null;
+      }
+
+      await chat.save();
+      logger.info('Relinked existing chat after provider migration', {
+        chatId: chat._id, oldChatId, newChatId: payload.chat_id,
+      });
+    }
+  }
+
+  // ─── New chat ──────────────────────────────────────────────
+  if (!chat) {
+    chat = await WhatsAppChat.create({
+      tenant_id: tenant._id,
+      unipile_chat_id: payload.chat_id,
+      unipile_account_id: payload.account_id,
+      contact_name: contactName,
+      contact_phone: contactPhone,
+      contact_profile_id: profile._id,
+      is_closed: false,
+      last_message_at: new Date(payload.timestamp),
+      last_message_preview: payload.message.substring(0, 100),
+      message_count: 0,
+    });
+
+    // Self-sent first message — our user initiated the chat
+    if (payload.is_sender) {
+      const session = await WhatsAppSession.create({
+        chat_id: chat._id,
+        tenant_id: tenant._id,
+        status: 'active',
+        started_at: new Date(),
+        taken_over_at: new Date(),
+      });
+      chat.active_session_id = session._id;
+      await chat.save();
+
+      await WhatsAppMessage.create({
+        chat_id: chat._id,
+        session_id: session._id,
+        tenant_id: tenant._id,
+        unipile_message_id: payload.message_id || null,
+        sender: 'human',
+        sender_name: 'WhatsApp',
+        text: payload.message,
+        sent_via_unipile: false,
+      });
+      chat.message_count = 1;
+      session.message_count = 1;
+      await Promise.all([chat.save(), session.save()]);
+      logger.info('Created new chat from self-sent message (human mode)', {
+        chatId: chat._id,
+        sessionId: session._id,
+        contact: contactName,
+      });
+      return;
+    }
+
+    if (skipAI) {
+      await WhatsAppMessage.create({
+        chat_id: chat._id,
+        session_id: null,
+        tenant_id: tenant._id,
+        unipile_message_id: payload.message_id || null,
+        sender: 'contact',
+        sender_name: contactName,
+        text: payload.message,
+        media_type: payload.content_type || null,
+        ad_context: payload.ad_context || null,
+        sent_via_unipile: false,
+      });
+      chat.message_count = 1;
+      await chat.save();
+      await WhatsAppContactProfile.updateOne({ _id: profile._id }, { $inc: { total_messages: 1 } });
+      logger.info('Created new chat — AI skipped', {
+        chatId: chat._id,
+        contact: contactName,
+        reason: isSystemMessage ? 'system_message' : 'blacklisted',
+      });
+      return;
+    }
+
+    const session = await createSession(chat, tenant._id.toString(), gracePeriodSeconds);
+
+    await WhatsAppMessage.create({
+      chat_id: chat._id,
+      session_id: session._id,
+      tenant_id: tenant._id,
+      unipile_message_id: payload.message_id || null,
+      sender: 'contact',
+      sender_name: contactName,
+      text: payload.message,
+      media_type: payload.content_type || null,
+      ad_context: payload.ad_context || null,
+      sent_via_unipile: false,
+    });
+    chat.message_count = 1;
+    await chat.save();
+    await WhatsAppContactProfile.updateOne({ _id: profile._id }, { $inc: { total_messages: 1 } });
+
+    session.message_count = 1;
+    await session.save();
+
+    logger.info('Created new WhatsApp chat with session', {
+      chatId: chat._id,
+      sessionId: session._id,
+      contact: contactName,
+      gracePeriodSeconds,
+    });
+
+    // Send fixed first message if enabled
+    const fixedMsg = tenant.settings?.whatsapp_agent?.fixed_first_message;
+    if (tenant.settings?.whatsapp_agent?.fixed_first_message_enabled && fixedMsg) {
+      const provider = unipileService.getProviderForTenant(tenant);
+      const chatRef = chat;
+      unipileService.sendMessage(provider, chatRef.unipile_chat_id, fixedMsg).then(async (result) => {
+        await WhatsAppMessage.create({
+          chat_id: chatRef._id,
+          session_id: session._id,
+          tenant_id: tenant._id,
+          unipile_message_id: result.message_id || null,
+          sender: 'system',
+          sender_name: 'AI',
+          text: fixedMsg,
+          sent_via_unipile: true,
+        });
+        chatRef.message_count += 1;
+        await chatRef.save();
+      }).catch(err => {
+        logger.error('Failed to send fixed first message', { chatId: chatRef._id, error: (err as Error).message });
+      });
+    }
+
+    await whatsappAgentService.startSession({
+      session,
+      gracePeriodSeconds,
+      agentId,
+      tenantId: tenant._id.toString(),
+    });
+    return;
+  }
+
+  // Backfill profile link on existing chats
+  if (!chat.contact_profile_id) {
+    chat.contact_profile_id = profile._id;
+    await chat.save();
+  }
+
+  // Update contact name if changed
+  if (chat.contact_name !== contactName && contactName !== 'Bilinmiyor') {
+    chat.contact_name = contactName;
+    await chat.save();
+  }
+
+  // ─── Self-sent messages (is_sender=true) ───────────────────
+  if (payload.is_sender) {
+    // Look up active session
+    let session = chat.active_session_id
+      ? await WhatsAppSession.findById(chat.active_session_id)
+      : null;
+    if (session && session.status === 'resolved') session = null;
+
+    // If session is waiting, human responded — cancel timer & resolve
+    let resolvedSessionId: mongoose.Types.ObjectId | null = null;
+    if (session && session.status === 'waiting') {
+      resolvedSessionId = session._id;
+      await whatsappAgentService.resolveSessionAsHuman(session);
+      session = null; // session is now resolved
+    }
+
+    // Check if we already stored this message (sent via our API)
+    // Primary dedup: by unipile_message_id (if Unipile returned one when we sent)
+    // Fallback dedup: by text + sent_via_unipile + recent timestamp (covers cases
+    // where Unipile didn't return a message_id in the send response)
+    if (payload.message_id) {
+      const exists = await WhatsAppMessage.findOne({ unipile_message_id: payload.message_id });
+      if (exists) {
+        logger.debug('Self-sent message already in DB (by message_id), skipping', { message_id: payload.message_id });
+        return;
+      }
+    }
+    const recentCutoff = new Date(Date.now() - 60_000); // 1 minute window
+    const existsByContent = await WhatsAppMessage.findOne({
+      chat_id: chat._id,
+      sent_via_unipile: true,
+      text: payload.message,
+      createdAt: { $gte: recentCutoff },
+    });
+    if (existsByContent) {
+      // Update the stored message with the real unipile_message_id for future dedup
+      if (payload.message_id && !existsByContent.unipile_message_id) {
+        await WhatsAppMessage.updateOne(
+          { _id: existsByContent._id },
+          { unipile_message_id: payload.message_id },
+        );
+      }
+      logger.debug('Self-sent message already in DB (by content), skipping', { message_id: payload.message_id });
+      return;
+    }
+
+    // Store the message — link to the session it resolved (if any) or the current active session
+    await WhatsAppMessage.create({
+      chat_id: chat._id,
+      session_id: resolvedSessionId || session?._id || null,
+      tenant_id: tenant._id,
+      unipile_message_id: payload.message_id,
+      sender: 'human',
+      sender_name: 'WhatsApp',
+      text: payload.message,
+      sent_via_unipile: false,
+    });
+
+    chat.last_message_at = new Date(payload.timestamp);
+    chat.last_message_preview = payload.message.substring(0, 100);
+    chat.message_count += 1;
+    await chat.save();
+
+    // If session is active with no takeover (AI mode), switch to human
+    if (session && session.status === 'active' && !session.taken_over_by && !session.taken_over_at) {
+      session.taken_over_at = new Date();
+      await session.save();
+      whatsappAgentService.closeConnection(chat.unipile_chat_id);
+      logger.info('Auto-switched to human mode (manual WhatsApp reply detected)', {
+        chatId: chat._id,
+        sessionId: session._id,
+      });
+    }
+
+    logger.info('Stored self-sent message from WhatsApp', { chatId: chat._id });
+    return;
+  }
+
+  // ─── Incoming contact message (is_sender=false) ────────────
+
+  // Blacklisted numbers & system messages: store but never trigger session or AI
+  if (skipAI) {
+    await WhatsAppMessage.create({
+      chat_id: chat._id,
+      session_id: null,
+      tenant_id: tenant._id,
+      unipile_message_id: payload.message_id || null,
+      sender: 'contact',
+      sender_name: contactName,
+      text: payload.message,
+      media_type: payload.content_type || null,
+      ad_context: payload.ad_context || null,
+      sent_via_unipile: false,
+    });
+    chat.last_message_at = new Date(payload.timestamp);
+    chat.last_message_preview = payload.message.substring(0, 100);
+    chat.message_count += 1;
+    if (chat.is_closed) chat.is_closed = false;
+    if (chat.deleted_at) chat.deleted_at = null;
+    await chat.save();
+    await WhatsAppContactProfile.updateOne({ _id: profile._id }, { $inc: { total_messages: 1 } });
+    logger.info('Message stored — AI skipped', {
+      chatId: chat._id,
+      reason: isSystemMessage ? 'system_message' : 'blacklisted',
+    });
+    return;
+  }
+
+  // Look up active session
+  let session = chat.active_session_id
+    ? await WhatsAppSession.findById(chat.active_session_id)
+    : null;
+  if (session && session.status === 'resolved') {
+    session = null;
+    chat.active_session_id = null;
+    await chat.save();
+  }
+
+  // If session is waiting, just store the message (timer already running)
+  if (session && session.status === 'waiting') {
+    await WhatsAppMessage.create({
+      chat_id: chat._id,
+      session_id: session._id,
+      tenant_id: tenant._id,
+      unipile_message_id: payload.message_id || null,
+      sender: 'contact',
+      sender_name: contactName,
+      text: payload.message,
+      media_type: payload.content_type || null,
+      ad_context: payload.ad_context || null,
+      sent_via_unipile: false,
+    });
+    chat.last_message_at = new Date(payload.timestamp);
+    chat.last_message_preview = payload.message.substring(0, 100);
+    chat.message_count += 1;
+    await chat.save();
+    session.message_count += 1;
+    await session.save();
+    await WhatsAppContactProfile.updateOne({ _id: profile._id }, { $inc: { total_messages: 1 } });
+    logger.info('Message stored during grace period', { chatId: chat._id, sessionId: session._id });
+    return;
+  }
+
+  // If session is active, forward to agent service
+  if (session && session.status === 'active') {
+    await whatsappAgentService.handleIncomingMessage({
+      tenantId: tenant._id.toString(),
+      agentId,
+      chat,
+      session,
+      messageText: payload.message,
+      senderName: contactName,
+      unipileMessageId: payload.message_id,
+      contentType: payload.content_type,
+    });
+    await WhatsAppContactProfile.updateOne({ _id: profile._id }, { $inc: { total_messages: 1 } });
+    return;
+  }
+
+  // No active session → create new one (closed or idle chat)
+  session = await createSession(chat, tenant._id.toString(), gracePeriodSeconds);
+
+  await WhatsAppMessage.create({
+    chat_id: chat._id,
+    session_id: session._id,
+    tenant_id: tenant._id,
+    unipile_message_id: payload.message_id || null,
+    sender: 'contact',
+    sender_name: contactName,
+    text: payload.message,
+    media_type: payload.content_type || null,
+    ad_context: payload.ad_context || null,
+    sent_via_unipile: false,
+  });
+  chat.last_message_at = new Date(payload.timestamp);
+  chat.last_message_preview = payload.message.substring(0, 100);
+  chat.message_count += 1;
+  await chat.save();
+  await WhatsAppContactProfile.updateOne({ _id: profile._id }, { $inc: { total_messages: 1 } });
+
+  session.message_count = 1;
+  await session.save();
+
+  await whatsappAgentService.startSession({
+    session,
+    gracePeriodSeconds,
+    agentId,
+    tenantId: tenant._id.toString(),
+  });
+
+  logger.info('Started new session for chat', {
+    chatId: chat._id,
+    sessionId: session._id,
+  });
+}
+
+// ─── Operator Workflow Helpers ──────────────────────────────
+
+/**
+ * Handle a reply from the operator (doctor) that contains a REF code.
+ * Matches the reply to the correct patient session and injects the response.
+ */
+async function handleOperatorReply(
+  tenant: InstanceType<typeof Tenant>,
+  payload: UnipileWebhookPayload,
+): Promise<void> {
+  const messageText = payload.message.trim();
+  const provider = unipileService.getProviderForTenant(tenant);
+
+  // Extract REF code from the message text or quoted (replied-to) message
+  const refMatch = messageText.match(/\b([A-Z]-[A-Z0-9]{4})\b/)
+    || (payload.quoted_text?.match(/\b([A-Z]-[A-Z0-9]{4})\b/) ?? null);
+  if (!refMatch) {
+    logger.info('Operator message without REF code — storing as normal', {
+      message: messageText.substring(0, 100),
+    });
+    // No REF code — this is just a normal message from the doctor, ignore it
+    // (could also store it as a chat message, but the doctor is messaging the clinic number)
+    return;
+  }
+
+  const refCode = refMatch[1];
+  // Match pending OR recently responded (estetisyen may send document after text reply)
+  const request = await OperatorRequest.findOne({
+    ref_code: refCode,
+    tenant_id: tenant._id,
+    status: { $in: ['pending', 'responded'] },
+  }).sort({ createdAt: -1 });
+
+  if (!request) {
+    logger.warn('No matching OperatorRequest for REF code', { refCode, tenantId: tenant._id });
+    return;
+  }
+
+  // Check if operator sent media (document/image) along with the reply
+  const hasMedia = !!payload.content_type && payload.content_type !== 'conversation' && payload.content_type !== 'extendedTextMessage';
+
+  logger.info('Operator reply media check', {
+    refCode,
+    content_type: payload.content_type,
+    message_id: payload.message_id,
+    chat_id: payload.chat_id,
+    hasMedia,
+    is_sender: payload.is_sender,
+  });
+
+  const alreadyResponded = request.status === 'responded';
+
+  // Update the operator request
+  request.status = 'responded';
+  if (!alreadyResponded) {
+    request.operator_response = messageText;
+    request.responded_at = new Date();
+  }
+  if (hasMedia) {
+    request.response_media_type = payload.content_type!;
+    request.response_message_id = payload.message_id;
+  }
+  await request.save();
+
+  // If operator sent media, forward it directly to the patient
+  let mediaForwarded = false;
+  if (hasMedia) {
+    const chat = await WhatsAppChat.findById(request.chat_id).lean();
+    if (chat) {
+      try {
+        // Small delay to ensure Baileys worker has cached the media
+        await new Promise(resolve => setTimeout(resolve, 1000));
+        await unipileService.forwardMedia(
+          provider,
+          payload.chat_id,
+          payload.message_id,
+          chat.contact_phone,
+          '',
+        );
+        mediaForwarded = true;
+        logger.info('Forwarded operator document to patient', {
+          refCode, mediaType: payload.content_type, patientPhone: chat.contact_phone,
+        });
+      } catch (err) {
+        logger.error('Failed to forward operator document to patient', {
+          refCode, error: (err as Error).message,
+        });
+      }
+    }
+  }
+
+  if (!alreadyResponded) {
+    // First reply: inject the operator's text response into the patient's AI session
+    await whatsappAgentService.injectOperatorResponse({
+      tenantId: tenant._id.toString(),
+      sessionId: request.session_id.toString(),
+      chatId: request.chat_id.toString(),
+      operatorResponse: messageText,
+      refCode,
+      hasDocument: mediaForwarded,
+    });
+
+    // Send confirmation to the estetisyen
+    try {
+      const accountId = tenant.settings.whatsapp_agent.unipile_account_id;
+      if (accountId) {
+        const operatorPhone = tenant.settings.whatsapp_agent.operator_phone!;
+        const operatorJid = operatorPhone.replace(/[^0-9]/g, '') + '@s.whatsapp.net';
+        const operatorChatId = `${accountId}:${operatorJid}`;
+        const confirmMsg = mediaForwarded
+          ? `✓ Yanıt ve belge hastaya iletildi. Ref: ${refCode}`
+          : `✓ Yanıt alındı. Ref: ${refCode} — Hastaya iletilecek.`;
+        await unipileService.sendMessage(provider, operatorChatId, confirmMsg);
+      }
+    } catch (err) {
+      logger.error('Failed to send confirmation to operator', { refCode, error: (err as Error).message });
+    }
+  } else if (mediaForwarded) {
+    // Follow-up: estetisyen sent document after initial text reply
+    // Notify AI about the document so it can tell the patient
+    await whatsappAgentService.injectOperatorResponse({
+      tenantId: tenant._id.toString(),
+      sessionId: request.session_id.toString(),
+      chatId: request.chat_id.toString(),
+      operatorResponse: '',
+      refCode,
+      hasDocument: true,
+    });
+
+    // Send confirmation
+    try {
+      const accountId = tenant.settings.whatsapp_agent.unipile_account_id;
+      if (accountId) {
+        const operatorPhone = tenant.settings.whatsapp_agent.operator_phone!;
+        const operatorJid = operatorPhone.replace(/[^0-9]/g, '') + '@s.whatsapp.net';
+        const operatorChatId = `${accountId}:${operatorJid}`;
+        await unipileService.sendMessage(provider, operatorChatId, `✓ Belge hastaya iletildi. Ref: ${refCode}`);
+      }
+    } catch (err) {
+      logger.error('Failed to send confirmation to operator', { refCode, error: (err as Error).message });
+    }
+  }
+
+  logger.info('Operator reply processed', {
+    refCode,
+    sessionId: request.session_id,
+    hasMedia,
+    mediaForwarded,
+    alreadyResponded,
+    response: messageText.substring(0, 100),
+  });
+}