Como adicionar um chatbot com IA a um app React (Vite, CRA, SPA)

Você precisa de duas coisas antes de mexer no código:

• Uma conta na Nexoply e a chave do seu chatbot. Cadastre-se grátis (o plano Free inclui 100 conversas por mês, sem cartão) e abra Chatbot no painel. O código de instalação dessa página já vem com a sua chave. A chave é pública: não é um segredo e não dá acesso à conta, então pode ficar no código do cliente.
• As informações do negócio que o assistente usa para responder: serviços e preços, perguntas frequentes, políticas, horários e áreas de atendimento. O jeito mais rápido é digitar o endereço do site e deixar a Nexoply importar as páginas públicas, inclusive páginas feitas com JavaScript, então um site em React também funciona. Nada é adicionado sem aprovação.

Toda SPA em React tem um HTML base. No Vite é o index.html na raiz do projeto; no Create React App é o public/index.html. Cole o código logo antes da tag de fechamento </body>:

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>

  <!-- Chatbot com IA da Nexoply -->
  <script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>
</body>

Troque YOUR-KEY pela chave da página Chatbot. O script carrega de forma assíncrona, então nunca bloqueia a renderização do seu app. Adicione data-open="true" à tag se quiser que a janela de chat abra ao carregar. Essa é a instalação inteira: faça o build, publique e o botão aparece em todas as rotas.

Carregue pelo código quando quiser controlar quando ele aparece, por exemplo só depois que o visitante aceitar o aviso de cookies, ou para manter a chave em uma variável de ambiente por ambiente de deploy. No Vite, coloque VITE_NEXOPLY_KEY=sua-chave em um arquivo .env e adicione isto ao componente raiz:

// src/App.tsx
import { useEffect } from "react";

const NEXOPLY_KEY: string = import.meta.env.VITE_NEXOPLY_KEY;

export default function App() {
  useEffect(() => {
    // Já está na página? Nada a fazer.
    if (document.querySelector("script[data-chatbot]")) return;
    const s = document.createElement("script");
    s.src = "https://nexoply.com/widget.js";
    s.async = true;
    s.dataset.chatbot = NEXOPLY_KEY;
    document.body.appendChild(s);
  }, []);

  return <main>{/* seu app */}</main>;
}

O widget lê as configurações da própria tag script, então a tag precisa manter o atributo data-chatbot e um src que contenha widget.js. Definir s.dataset.chatbot cria esse atributo. O Create React App não tem import.meta.env: lá, use process.env.REACT_APP_NEXOPLY_KEY.

• Por que não há função de limpeza. O widget não tem API para removê-lo depois de carregado, e ele vive fora da árvore do React, então desmontar o App não precisa desfazer nada. Deixe esse efeito no componente raiz, que fica montado durante toda a visita.
• Por que o StrictMode não é problema. Em desenvolvimento, o React StrictMode executa os efeitos duas vezes. A verificação com querySelector pula a segunda execução, e mesmo que o script fosse adicionado duas vezes, o widget é montado uma única vez por chave de chatbot. Pelo mesmo motivo, o hot reload também é seguro.

• Fica fora da árvore do React. O widget é montado em document.body, fora do seu elemento #root, então re-renders e mudanças de rota nunca o removem nem mudam o estilo dele.
• Shadow DOM nos dois sentidos. O seu CSS (Tailwind, CSS modules, resets globais) não vaza para o chat, e o CSS dele não vaza para o seu app.
• Mudanças de rota funcionam sozinhas. Com React Router ou qualquer router baseado no histórico, os visitantes mantêm a conversa enquanto navegam, e as regras de página (como uma aba lateral só em /pricing) são verificadas de novo quando a URL muda. Sem código extra.
• Sem cookies. Ele guarda um identificador anônimo do visitante no localStorage e a conversa atual no sessionStorage.

Quer um botão "Fale com a gente" na página inicial ou na página de preços? Dispare o evento nexoply:open-chat em window:

export function ChatButton() {
  return (
    <button onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}>
      Fale com a gente
    </button>
  );
}

Não precisa de nenhum import: o widget escuta esse evento em window. Se preferir mostrar só o seu próprio botão, defina o botão de mensagem como "Sem botão" com uma regra de página no painel.

Antes de publicar, confira estes três pontos:

• Sites permitidos. Se você preencheu Permitir apenas nestes sites (painel → Chatbot), adicione o seu host de desenvolvimento com a porta, como localhost:5173 para o Vite ou localhost:3000 para o Create React App, ou deixe a lista vazia enquanto testa.
• Content-Security-Policy. Se o seu app envia um cabeçalho ou meta tag de CSP, permita https://nexoply.com em script-src, connect-src e img-src.
• Teste de ponta a ponta. Rode o app, clique no botão de chat, faça uma pergunta real e procure por ela em Conversas no painel.

Se o botão ainda não aparecer:

• Chave vazia. Mostre NEXOPLY_KEY no console. O Vite só expõe variáveis que começam com VITE_, e é preciso reiniciar o servidor de desenvolvimento depois de editar o .env.
• Requisição bloqueada. Veja o console e a aba Network do navegador em busca de erros de CSP ou de um widget.js bloqueado.
• Chatbot desligado. Verifique se a chave Chatbot ativado está ligada.
• Bloqueadores de anúncios. Raramente, uma extensão do navegador bloqueia widgets de chat. Teste em uma janela anônima sem extensões.

Depois que o script está no lugar, você não precisa mexer no código de novo: as alterações feitas no painel chegam ao site em cerca de um minuto. Em Chatbot → Personalizar você define o estilo do botão de mensagem (ícone ou uma imagem ou SVG seu, texto, formato, tamanho, cores, posição) ou usa no lugar uma aba lateral na borda da tela. Defina um visual diferente no celular e use regras de página para mudá-lo em rotas específicas (por exemplo /pricing, ou /servicos/*). A janela de chat usa suas fontes, cores e logo, e a tela inicial pode oferecer botões como Agendar, Ligar ou WhatsApp.

Usa outro framework? Veja o guia do Next.js ou o guia do Vue. Para a visão completa, leia como funciona ou compare os planos.