"Que eventos posso escutar com a FlowHunt JS API?"

"A FlowHunt JS API emite 10 eventos: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall e onFHError. Pode subscrevê-los usando window.addEventListener ou através dos métodos de callback do chatbot manager."

"Como escondo o botão de chat padrão e abro o chatbot programaticamente?"

"Utilize a opção de configuração showChatButton: false para esconder o botão padrão e depois chame chatbotManager.openChat() para abrir o chatbot nos seus próprios termos — por exemplo, ao clicar num botão personalizado."

"Qual é a diferença entre os métodos de callback do manager e window.addEventListener?"

"Ambas as abordagens funcionam. Os métodos de callback do manager (por exemplo, chatbotManager.onMessageSent(fn)) são chamados dentro do callback init e estão vinculados à instância do manager. A abordagem window.addEventListener (por exemplo, window.addEventListener('onFHMessageSent', fn)) pode ser configurada em qualquer parte da página, mesmo antes do chatbot carregar."

"Como passo dados personalizados para o chatbot usando variáveis de fluxo?"

"Utilize a opção de configuração flowVariables em setConfig() para passar pares chave-valor como ID de utilizador, email ou URL da página. Estas variáveis ficam disponíveis dentro do fluxo do chatbot para respostas personalizadas."

"Que dados estão disponíveis nos manipuladores de eventos?"

"Os eventos que transportam dados incluem-nos em event.detail.metadata. Por exemplo, onFHMessageSent inclui o conteúdo da mensagem e o timestamp, onFHMessageReceived inclui o flow_id, message_id e o texto da mensagem, e onFHFeedback inclui o message_id e se o feedback foi positivo ou negativo."

Automação de IA

FlowHunt JS API: Guia de Integração para Utilizadores Avançados

Referência completa para a integração da FlowHunt JS API v2. Aprenda a incorporar o chatbot, subscrever todos os 10 eventos, utilizar variáveis de fluxo, rastrear interações com parâmetros de URL e controlar a janela de chat programaticamente.

FlowHunt JavaScript API Chatbot Integration

A FlowHunt JS API dá-lhe controlo total sobre como o seu chatbot se integra com o seu website. Utilizando o código de integração v2, pode incorporar o chatbot, subscrever eventos de ciclo de vida e interação, passar dados dinâmicos através de variáveis de fluxo, rastrear interações com parâmetros de URL e controlar programaticamente a janela de chat.

Este guia cobre todos os aspetos da JS API com exemplos de código que pode copiar e adaptar ao seu projeto.

Código de Integração (v2)

Quando cria um chatbot no FlowHunt, obtém um snippet de integração. Copie e cole-o no seu HTML imediatamente antes da tag de fecho </body>:

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // The chatbot is ready — use chatbotManager here
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Substitua YOUR_CHATBOT_ID e YOUR_WORKSPACE_ID pelos valores do seu painel FlowHunt. O ID do chatbot no nome da variável global (window.FHChatbot_YOUR_CHATBOT_ID) utiliza underscores em vez de hífens.

Substituir a Configuração com setConfig()

Antes de chamar init(), pode substituir as configurações padrão do chatbot usando setConfig():

<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      headerTitle: 'Support Assistant',
      maxWindowWidth: '700px',
      showChatButton: false,
      flowVariables: {
        userId: '12345',
        plan: 'enterprise'
      },
      urlSuffix: '?utm_source=chatbot'
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Chatbot initialized with custom config
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Opções de Configuração Disponíveis

Option	Type	Description
`headerTitle`	string	Texto personalizado do título do cabeçalho
`maxWindowWidth`	string	Largura máxima da janela de chat (por exemplo, `'700px'`)
`maxWindowHeight`	string	Altura máxima da janela de chat
`inputPlaceholder`	string	Texto de espaço reservado para o campo de entrada de mensagens
`showChatButton`	boolean	Mostrar ou esconder o botão flutuante de chat padrão
`openChatPanel`	boolean	Abrir automaticamente o painel de chat ao carregar a página
`flowVariables`	object	Pares chave-valor de dados personalizados passados para o fluxo
`urlSuffix`	string	Cadeia de consulta anexada a todos os URLs gerados pelo chatbot
`cookieConsent`	boolean	Ativar persistência de sessão via cookies
`embedded`	string	Definir para ativar o modo incorporado (sem botão de fechar)
`theme`	string	Modo de tema

Variáveis de Fluxo: Passar Dados Dinâmicos

As variáveis de fluxo permitem-lhe enviar dados personalizados do seu website para o fluxo do chatbot. Isto permite conversas personalizadas com base no contexto do utilizador.

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  flowVariables: {
    userId: getCurrentUserId(),
    userEmail: getCurrentUserEmail(),
    currentPage: window.location.pathname,
    plan: 'enterprise'
  }
});

Uma vez definidas, estas variáveis ficam acessíveis dentro da lógica do fluxo do chatbot, permitindo personalizar respostas, encaminhar conversas ou passar contexto para agentes de IA.

URL Suffix: Rastrear Interações do Chatbot

O parâmetro urlSuffix anexa uma cadeia de consulta a cada URL gerado pelo chatbot. Isto é útil para rastrear o tráfego originado pelo chatbot em ferramentas de análise:

window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
  urlSuffix: '?utm_source=chatbot&utm_medium=widget'
});

Casos de uso:

Rastrear conversões a partir de interações do chatbot no Google Analytics.
Analisar o comportamento do utilizador após interagir com o chatbot.
Atribuir campanhas que impulsionam o envolvimento com o chatbot.

Referência de Eventos

A FlowHunt JS API despacha 10 eventos personalizados no objeto window. Todos os eventos utilizam a API CustomEvent com bubbles: true e composed: true.

onFHChatbotReady

Disparado quando o widget do chatbot foi completamente renderizado e está pronto para uso.

Dados do evento: Nenhum
Quando: Após o DOM do widget ser montado e o botão de chat estar visível.

onFHChatbotSessionCreated

Disparado quando uma nova sessão de chat é criada no servidor. Também é disparado quando a sessão é reiniciada.

Dados do evento: Nenhum
Quando: Após uma chamada de API de criação de sessão bem-sucedida.

onFHChatbotWindowOpened

Disparado quando o utilizador abre a janela de chat.

Dados do evento: Nenhum
Quando: O painel de chat torna-se visível.
Nota: Não é disparado no modo incorporado.

onFHChatbotWindowClosed

Disparado quando o utilizador fecha a janela de chat.

Dados do evento: Nenhum
Quando: O painel de chat é ocultado.
Nota: Não é disparado no modo incorporado.

onFHMessageSent

Disparado quando o utilizador envia uma mensagem.

Dados do evento (event.detail.metadata):

{
  "content": "Hello, I need help with...",
  "createdAt": "2026-02-19T10:30:00.000Z"
}

onFHMessageReceived

Disparado quando o chatbot recebe e exibe uma resposta.

Dados do evento (event.detail.metadata):

{
  "flow_id": "abc123",
  "message_id": "msg_456",
  "message": "Sure, I can help you with that!",
  "sender": {
    "sender_name": "Support Agent",
    "sender_avatar": "https://example.com/avatar.png"
  }
}

O campo sender é opcional e só está presente quando um agente humano está envolvido.

onFHFormDataSent

Disparado quando o utilizador submete dados de formulário através do chatbot.

Dados do evento (event.detail.metadata):

{
  "objectData": { "name": "John", "email": "john@example.com" },
  "createdAt": "2026-02-19T10:31:00.000Z"
}

onFHFeedback

Disparado quando um utilizador dá feedback de polegar para cima ou polegar para baixo numa mensagem do chatbot.

Dados do evento (event.detail.metadata):

{
  "message_id": "msg_456",
  "content": "Optional feedback text",
  "feedback": "P"
}

O valor feedback é "P" para positivo (polegar para cima) ou "N" para negativo (polegar para baixo).

onFHToolCall

Disparado quando uma ferramenta ou ação é executada durante o processamento do fluxo.

Dados do evento (event.detail.metadata):

{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_789",
    "message": "Calling search API..."
  },
  "createdAt": "2026-02-19T10:32:00.000Z"
}

Nota: Apenas disparado nos modos flowAssistant e flowAssistantV3, não no modo chatbot padrão.

onFHError

Disparado quando ocorre um erro durante a operação do chatbot.

Dados do evento (event.detail.metadata):

{
  "metadata": {
    "flow_id": "abc123",
    "message_id": "msg_err",
    "message": "Flow execution failed"
  },
  "createdAt": "2026-02-19T10:33:00.000Z"
}

Subscrever Eventos

Existem duas formas de subscrever eventos do chatbot.

Método 1: Escutadores de Eventos da Janela

Utilize window.addEventListener em qualquer parte da sua página. Isto funciona mesmo antes do chatbot ter carregado:

<script>
document.addEventListener('DOMContentLoaded', function() {
  // Chatbot lifecycle events
  window.addEventListener('onFHChatbotReady', function(event) {
    console.log('Chatbot is ready');
  });

  window.addEventListener('onFHChatbotSessionCreated', function(event) {
    console.log('Session created');
  });

  window.addEventListener('onFHChatbotWindowOpened', function(event) {
    console.log('Chat window opened');
  });

  window.addEventListener('onFHChatbotWindowClosed', function(event) {
    console.log('Chat window closed');
  });

  // Message events
  window.addEventListener('onFHMessageSent', function(event) {
    console.log('User sent:', event.detail.metadata.content);
  });

  window.addEventListener('onFHMessageReceived', function(event) {
    console.log('Bot replied:', event.detail.metadata.message);
  });

  window.addEventListener('onFHFormDataSent', function(event) {
    console.log('Form submitted:', event.detail.metadata.objectData);
  });

  // Feedback
  window.addEventListener('onFHFeedback', function(event) {
    var feedback = event.detail.metadata;
    console.log('Feedback on message', feedback.message_id, ':',
      feedback.feedback);
  });

  // Tool calls (flowAssistant modes only)
  window.addEventListener('onFHToolCall', function(event) {
    console.log('Tool called:', event.detail.metadata);
  });

  // Errors
  window.addEventListener('onFHError', function(event) {
    console.error('Chatbot error:', event.detail.metadata);
  });
});
</script>

Para parar de escutar um evento, utilize removeEventListener com a mesma referência de função:

var handleMessage = function(event) {
  console.log(event.detail.metadata);
};
window.addEventListener('onFHMessageReceived', handleMessage);

// Later, when you want to stop listening:
window.removeEventListener('onFHMessageReceived', handleMessage);

Método 2: Métodos de Callback do Manager

Dentro do callback init(), utilize os métodos integrados do chatbot manager:

window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
  chatbotManager.onSessionCreated(function() {
    console.log('Session created');
  });

  chatbotManager.onWindowOpened(function() {
    console.log('Window opened');
  });

  chatbotManager.onWindowClosed(function() {
    console.log('Window closed');
  });

  chatbotManager.onMessageSent(function(event) {
    console.log('User sent:', event.metadata);
  });

  chatbotManager.onMessageReceived(function(event) {
    console.log('Bot replied:', event.metadata);
  });

  chatbotManager.onFormDataSent(function(event) {
    console.log('Form data:', event.metadata);
  });

  chatbotManager.onFeedback(function(event) {
    console.log('Feedback:', event.metadata);
  });

  chatbotManager.onToolCall(function(event) {
    console.log('Tool call:', event.metadata);
  });

  chatbotManager.onError(function(event) {
    console.error('Error:', event.metadata);
  });
});

Referência de Métodos do Manager

Method	Parameters	Description
`onSessionCreated(fn)`	`fn: () => void`	Escutar a criação de sessão
`onWindowOpened(fn)`	`fn: () => void`	Escutar a abertura da janela
`onWindowClosed(fn)`	`fn: () => void`	Escutar o fecho da janela
`onMessageSent(fn)`	`fn: (event) => void`	Escutar mensagens do utilizador
`onMessageReceived(fn)`	`fn: (event) => void`	Escutar respostas do bot
`onFormDataSent(fn)`	`fn: (event) => void`	Escutar submissões de formulário
`onFeedback(fn)`	`fn: (event) => void`	Escutar feedback do utilizador
`onToolCall(fn)`	`fn: (event) => void`	Escutar execuções de ferramentas
`onError(fn)`	`fn: (event) => void`	Escutar erros
`openChat()`	—	Abre o painel de chat
`closeChat()`	—	Fecha o painel de chat

Ativação Personalizada do Chat: Esconder o Botão e Abrir ao Clicar

Para controlar totalmente quando o chatbot aparece, esconda o botão flutuante padrão e abra o chat programaticamente — por exemplo, a partir do seu próprio botão personalizado.

Exemplo Completo

<!-- Your custom chat button -->
<button id="my-chat-button">Chat with us</button>

<!-- FlowHunt integration with hidden default button -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      // Open chat when your custom button is clicked
      document.getElementById('my-chat-button')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Mostrar um Botão Personalizado Apenas Quando o Chatbot Está Pronto

Pode combinar a ativação oculta com escutadores de eventos para criar interações avançadas:

<button id="open-chat" style="display:none;">Need help?</button>

<script>
// Show a custom button only when the chatbot is ready
window.addEventListener('onFHChatbotReady', function() {
  document.getElementById('open-chat').style.display = 'block';
});
</script>

<!-- FlowHunt integration -->
<script id="fh-chatbot-script-YOUR_CHATBOT_ID">
  var currentScript = document.currentScript
    || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

  var script = document.createElement('script');
  script.async = true;
  script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
    + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

  script.onload = function() {
    window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
      showChatButton: false
    });

    window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
      document.getElementById('open-chat')
        .addEventListener('click', function() {
          chatbotManager.openChat();
        });
    });
  };

  if (currentScript && currentScript.parentNode) {
    currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
  } else {
    document.head.appendChild(script);
  }
</script>

Exemplo Completo de Integração

Um exemplo completo e funcional que demonstra substituições de configuração, rastreamento de eventos e ativação personalizada do chat em conjunto:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>FlowHunt Chatbot Integration</title>
</head>
<body>
  <h1>My Website</h1>
  <button id="open-chat-btn">Talk to our AI assistant</button>
  <button id="close-chat-btn">Close chat</button>

  <!-- Subscribe to events before the chatbot loads -->
  <script>
  document.addEventListener('DOMContentLoaded', function() {
    window.addEventListener('onFHChatbotReady', function() {
      console.log('Chatbot widget is ready');
    });

    window.addEventListener('onFHChatbotSessionCreated', function() {
      console.log('New chat session started');
    });

    window.addEventListener('onFHMessageSent', function(event) {
      console.log('User message:', event.detail.metadata.content);
    });

    window.addEventListener('onFHMessageReceived', function(event) {
      console.log('Bot response:', event.detail.metadata.message);
    });

    window.addEventListener('onFHFeedback', function(event) {
      var fb = event.detail.metadata;
      if (fb.feedback === 'P') {
        console.log('Positive feedback on message', fb.message_id);
      } else {
        console.log('Negative feedback on message', fb.message_id);
      }
    });

    window.addEventListener('onFHError', function(event) {
      console.error('Chatbot error:', event.detail.metadata);
    });
  });
  </script>

  <!-- FlowHunt integration -->
  <script id="fh-chatbot-script-YOUR_CHATBOT_ID">
    var currentScript = document.currentScript
      || document.getElementById('fh-chatbot-script-YOUR_CHATBOT_ID');

    var script = document.createElement('script');
    script.async = true;
    script.src = 'https://app.flowhunt.io/api/chatbot/YOUR_CHATBOT_ID'
      + '?workspace_id=YOUR_WORKSPACE_ID&v=2';

    script.onload = function() {
      window.FHChatbot_YOUR_CHATBOT_ID.setConfig({
        showChatButton: false,
        headerTitle: 'AI Assistant',
        maxWindowWidth: '600px',
        flowVariables: {
          source: 'website',
          page: window.location.pathname
        },
        urlSuffix: '?utm_source=chatbot'
      });

      window.FHChatbot_YOUR_CHATBOT_ID.init(function(chatbotManager) {
        document.getElementById('open-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.openChat();
          });

        document.getElementById('close-chat-btn')
          .addEventListener('click', function() {
            chatbotManager.closeChat();
          });
      });
    };

    if (currentScript && currentScript.parentNode) {
      currentScript.parentNode.insertBefore(script, currentScript.nextSibling);
    } else {
      document.head.appendChild(script);
    }
  </script>
</body>
</html>

Perguntas frequentes

Que eventos posso escutar com a FlowHunt JS API?: A FlowHunt JS API emite 10 eventos: onFHChatbotReady, onFHChatbotSessionCreated, onFHChatbotWindowOpened, onFHChatbotWindowClosed, onFHMessageSent, onFHMessageReceived, onFHFormDataSent, onFHFeedback, onFHToolCall e onFHError. Pode subscrevê-los usando window.addEventListener ou através dos métodos de callback do chatbot manager.
Como escondo o botão de chat padrão e abro o chatbot programaticamente?: Utilize a opção de configuração showChatButton: false para esconder o botão padrão e depois chame chatbotManager.openChat() para abrir o chatbot nos seus próprios termos — por exemplo, ao clicar num botão personalizado.
Qual é a diferença entre os métodos de callback do manager e window.addEventListener?: Ambas as abordagens funcionam. Os métodos de callback do manager (por exemplo, chatbotManager.onMessageSent(fn)) são chamados dentro do callback init e estão vinculados à instância do manager. A abordagem window.addEventListener (por exemplo, window.addEventListener('onFHMessageSent', fn)) pode ser configurada em qualquer parte da página, mesmo antes do chatbot carregar.
Como passo dados personalizados para o chatbot usando variáveis de fluxo?: Utilize a opção de configuração flowVariables em setConfig() para passar pares chave-valor como ID de utilizador, email ou URL da página. Estas variáveis ficam disponíveis dentro do fluxo do chatbot para respostas personalizadas.
Que dados estão disponíveis nos manipuladores de eventos?: Os eventos que transportam dados incluem-nos em event.detail.metadata. Por exemplo, onFHMessageSent inclui o conteúdo da mensagem e o timestamp, onFHMessageReceived inclui o flow_id, message_id e o texto da mensagem, e onFHFeedback inclui o message_id e se o feedback foi positivo ou negativo.