feat(typebot): detect [transfer_human] marker for bot-to-human handoff

sosamilton · sosamilton · commit c70d9c328fd9 · 2026-02-16T03:31:18.000-03:00
- Add detectTransferMarker to coordination config (env.config.ts)
- Typebot service detects [transfer_human] in bot responses
- On detection: pauses bot session + opens Chatwoot conversation
- Configurable per-instance via coordinationSettings
- ChatbotChatwootService: add getCoordinationConfig helper
diff --git a/src/api/integrations/chatbot/chatbot-chatwoot.service.ts b/src/api/integrations/chatbot/chatbot-chatwoot.service.ts
@@ -14,6 +14,7 @@ export interface CoordinationConfig {
   autoPause: boolean;
   autoResolve: boolean;
   manageEnabled: boolean;
+  detectTransferMarker: boolean;
 }
 
 /**
@@ -49,6 +50,7 @@ export class ChatbotChatwootService {
       autoPause: global.AUTO_PAUSE,
       autoResolve: global.AUTO_RESOLVE,
       manageEnabled: global.MANAGE_ENABLED,
+      detectTransferMarker: global.DETECT_TRANSFER_MARKER,
     };
   }
 
@@ -70,6 +72,7 @@ export class ChatbotChatwootService {
         autoPause: override.autoPause ?? defaults.autoPause,
         autoResolve: override.autoResolve ?? defaults.autoResolve,
         manageEnabled: override.manageEnabled ?? defaults.manageEnabled,
+        detectTransferMarker: override.detectTransferMarker ?? defaults.detectTransferMarker,
       };
     } catch (error) {
       this.logger.error(`[Coordination] Error reading instance config, using defaults: ${error?.message}`);
@@ -241,7 +244,7 @@ export class ChatbotChatwootService {
         },
         chatwootConversationId: { not: null },
       },
-      orderBy: { createdAt: 'desc' },
+      orderBy: { messageTimestamp: 'desc' },
     });
 
     if (recentMessage?.chatwootConversationId) {
diff --git a/src/api/integrations/chatbot/typebot/services/typebot.service.ts b/src/api/integrations/chatbot/typebot/services/typebot.service.ts
@@ -298,6 +298,24 @@ export class TypebotService extends BaseChatbotService<TypebotModel, any> {
       return null;
     };
 
+    let transferToHumanRequested = false;
+
+    // Check if [transfer_human] marker detection is enabled for this instance
+    let detectMarkerEnabled = true;
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      const { chatbotChatwootService: markerSvc } = require('@api/server.module');
+      if (markerSvc) {
+        const instDb = await this.prismaRepository.instance.findFirst({ where: { name: instance.instanceName } });
+        if (instDb) {
+          const cfg = await markerSvc.getCoordinationConfig(instDb.id);
+          detectMarkerEnabled = cfg.detectTransferMarker;
+        }
+      }
+    } catch {
+      // Default: enabled
+    }
+
     for (const message of messages) {
       if (message.type === 'text') {
         let formattedText = '';
@@ -313,6 +331,14 @@ export class TypebotService extends BaseChatbotService<TypebotModel, any> {
 
         formattedText = formattedText.replace(/\n$/, '');
 
+        // Detect [transfer_human] marker from Typebot flow (configurable per instance)
+        if (detectMarkerEnabled && formattedText.includes('[transfer_human]')) {
+          transferToHumanRequested = true;
+          formattedText = formattedText.replace('[transfer_human]', '').trim();
+          this.logger.log(`[Coordination] Detected [transfer_human] marker in Typebot message for ${session.remoteJid}`);
+          if (!formattedText) continue; // skip empty message after stripping marker
+        }
+
         if (formattedText.includes('[list]')) {
           await this.processListMessage(instance, formattedText, session.remoteJid);
         } else if (formattedText.includes('[buttons]')) {
@@ -408,55 +434,84 @@ export class TypebotService extends BaseChatbotService<TypebotModel, any> {
         },
       });
     } else {
-      let statusChange = 'closed';
-      if (!settings?.keepOpen) {
-        await prismaRepository.integrationSession.deleteMany({
-          where: {
-            id: session.id,
-          },
-        });
-        statusChange = 'delete';
+      // Check if transfer_human was requested via [transfer_human] marker or HTTP Request
+      const currentSession = await prismaRepository.integrationSession.findUnique({
+        where: { id: session.id },
+      });
+      const sessionPaused = currentSession?.status === 'paused';
+
+      if (transferToHumanRequested || sessionPaused) {
+        this.logger.log(
+          `[Coordination] Transfer to human requested for ${session.remoteJid} (marker: ${transferToHumanRequested}, paused: ${sessionPaused})`,
+        );
+
+        // Execute transfer_human logic internally
+        if (transferToHumanRequested && !sessionPaused) {
+          try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { chatbotChatwootService } = require('@api/server.module');
+            if (chatbotChatwootService) {
+              const instanceDb = await this.prismaRepository.instance.findFirst({ where: { name: instance.instanceName } });
+              if (instanceDb) {
+                const result = await chatbotChatwootService.transferToHuman(instanceDb.id, session.remoteJid);
+                this.logger.log(`[Coordination] transferToHuman result: ${JSON.stringify(result)}`);
+              }
+            }
+          } catch (err) {
+            this.logger.error(`[Coordination] Error executing transferToHuman: ${err?.message}`);
+          }
+        }
       } else {
-        await prismaRepository.integrationSession.update({
-          where: {
-            id: session.id,
-          },
-          data: {
-            status: 'closed',
-          },
-        });
-      }
+        let statusChange = 'closed';
+        if (!settings?.keepOpen) {
+          await prismaRepository.integrationSession.deleteMany({
+            where: {
+              id: session.id,
+            },
+          });
+          statusChange = 'delete';
+        } else {
+          await prismaRepository.integrationSession.update({
+            where: {
+              id: session.id,
+            },
+            data: {
+              status: 'closed',
+            },
+          });
+        }
 
-      // Coordination: resolve Chatwoot conversation when bot flow completes
-      // Respects autoResolve config (global env var + per-instance override)
-      try {
-        let shouldAutoResolve = true;
+        // Coordination: resolve Chatwoot conversation when bot flow completes
+        // Respects autoResolve config (global env var + per-instance override)
         try {
-          // eslint-disable-next-line @typescript-eslint/no-var-requires
-          const { chatbotChatwootService } = require('@api/server.module');
-          if (chatbotChatwootService) {
-            const instanceDb = await this.prismaRepository.instance.findFirst({ where: { name: instance.instanceName } });
-            if (instanceDb) {
-              const config = await chatbotChatwootService.getCoordinationConfig(instanceDb.id);
-              shouldAutoResolve = config.autoResolve;
+          let shouldAutoResolve = true;
+          try {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { chatbotChatwootService } = require('@api/server.module');
+            if (chatbotChatwootService) {
+              const instanceDb = await this.prismaRepository.instance.findFirst({ where: { name: instance.instanceName } });
+              if (instanceDb) {
+                const config = await chatbotChatwootService.getCoordinationConfig(instanceDb.id);
+                shouldAutoResolve = config.autoResolve;
+              }
             }
+          } catch {
+            // If service not available, use default (true)
           }
-        } catch {
-          // If service not available, use default (true)
-        }
-        if (shouldAutoResolve) {
-          await this.resolveChatwootConversation(session.remoteJid, instance);
+          if (shouldAutoResolve) {
+            await this.resolveChatwootConversation(session.remoteJid, instance);
+          }
+        } catch (error) {
+          this.logger.error(`[Coordination] Error checking autoResolve config: ${error?.message}`);
         }
-      } catch (error) {
-        this.logger.error(`[Coordination] Error checking autoResolve config: ${error?.message}`);
-      }
 
-      const typebotData = {
-        remoteJid: session.remoteJid,
-        status: statusChange,
-        session,
-      };
-      instance.sendDataWebhook(Events.TYPEBOT_CHANGE_STATUS, typebotData);
+        const typebotData = {
+          remoteJid: session.remoteJid,
+          status: statusChange,
+          session,
+        };
+        instance.sendDataWebhook(Events.TYPEBOT_CHANGE_STATUS, typebotData);
+      }
     }
   }
 
@@ -485,7 +540,7 @@ export class TypebotService extends BaseChatbotService<TypebotModel, any> {
           key: { path: ['remoteJid'], equals: remoteJid },
           chatwootConversationId: { not: null },
         },
-        orderBy: { createdAt: 'desc' },
+        orderBy: { messageTimestamp: 'desc' },
       });
 
       if (!recentMessage?.chatwootConversationId) {
diff --git a/src/config/env.config.ts b/src/config/env.config.ts
@@ -340,6 +340,7 @@ export type ChatbotCoordination = {
   AUTO_PAUSE: boolean;
   AUTO_RESOLVE: boolean;
   MANAGE_ENABLED: boolean;
+  DETECT_TRANSFER_MARKER: boolean;
 };
 
 export type S3 = {
@@ -852,6 +853,7 @@ export class ConfigService {
         AUTO_PAUSE: process.env?.CHATBOT_COORDINATION_AUTO_PAUSE !== 'false',
         AUTO_RESOLVE: process.env?.CHATBOT_COORDINATION_AUTO_RESOLVE !== 'false',
         MANAGE_ENABLED: process.env?.CHATBOT_COORDINATION_MANAGE_ENABLED !== 'false',
+        DETECT_TRANSFER_MARKER: process.env?.CHATBOT_COORDINATION_DETECT_TRANSFER_MARKER !== 'false',
       },
       CACHE: {
         REDIS: {
