Tutoriais

Chatbot em React: adicione um chatbot com IA ao seu app React (Vite, CRA, SPA)

Adicione um chatbot com IA em React JS com um componente <Chatbot /> ou uma tag script. Funciona com Vite, CRA e React Router. Sem npm nem chave de IA.

Atualizado em 12 de novembro de 2026 8 min de leitura

Em resumo

Para adicionar um chatbot em React JS, copie para seu app o pequeno componente <Chatbot /> abaixo: ele adiciona o script do Nexoply uma única vez a partir de um useEffect e não renderiza nada sozinho. Ou cole o script de uma linha no index.html, logo antes de </body>. Nos dois casos o botão de chat aparece em todas as rotas, sem pacote npm para instalar nem chave de IA para gerenciar: o assistente responde com as informações do negócio que você adiciona no painel.

  • Componente <Chatbot /> pronto para copiar: um useEffect que adiciona o script uma vez. Funciona como está com TypeScript, é seguro com StrictMode e não precisa de limpeza.
  • Não precisa de componente? Uma tag script no index.html antes de </body> (Vite: index.html na raiz do projeto; Create React App: public/index.html).
  • Ele é montado em document.body dentro de um Shadow DOM, fora da raiz do React, então re-renderizações, mudanças de rota e seu CSS nunca o afetam.
  • Abra o chat pelo seu próprio botão com window.dispatchEvent(new Event("nexoply:open-chat")).
  • Testando em localhost? Adicione seu host de desenvolvimento com a porta em Sites permitidos, ou deixe essa lista vazia.

Antes de começar

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

  • Uma conta no Nexoply e a chave do seu chatbot. Cadastre-se grátis (o plano Grátis inclui 50 conversas por mês, sem cartão) e abra Chatbot no painel. O código de instalação dessa página já vem com sua chave. A chave é pública: não é um segredo e não dá acesso à conta, então pode ficar no código que roda no navegador.
  • 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 o Nexoply importar as páginas públicas, inclusive páginas feitas com JavaScript, então um site em React também funciona. Quando você se cadastra com seu site, ele adiciona sozinho serviços, perguntas frequentes, horários, políticas e páginas, sem sobrescrever o que você digitou; uma análise que você iniciar depois pelo painel aparece primeiro para revisão.

Opção 1: Um componente de chatbot para React pronto para copiar

Crie src/components/Chatbot.tsx. O componente não renderiza nada sozinho: ele adiciona o script do Nexoply à página uma única vez, e o widget desenha o botão e a janela de chat.

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

type ChatbotProps = { chatbotKey: string };

export function Chatbot({ chatbotKey }: ChatbotProps) {
  useEffect(() => {
    // No key, or the script is already on the page: nothing to do.
    if (!chatbotKey || document.querySelector("script[data-chatbot]")) return;
    const s = document.createElement("script");
    s.src = "https://nexoply.com/widget.js";
    s.async = true;
    s.dataset.chatbot = chatbotKey;
    document.body.appendChild(s);
  }, [chatbotKey]);

  return null;
}

Renderize-o uma única vez, no componente que fica montado durante toda a visita (normalmente o App). No Vite, coloque VITE_NEXOPLY_KEY=YOUR-KEY em um arquivo .env:

// src/App.tsx
import { Chatbot } from "./components/Chatbot";

export default function App() {
  return (
    <>
      {/* your layout and routes */}
      <Chatbot chatbotKey={import.meta.env.VITE_NEXOPLY_KEY} />
    </>
  );
}

O componente funciona como está em um projeto TypeScript com Vite ou Create React App. Para JavaScript, chame o arquivo de Chatbot.jsx e remova o tipo ChatbotProps. O Create React App não tem import.meta.env: passe process.env.REACT_APP_NEXOPLY_KEY no lugar. Como é um componente comum, você também pode renderizá-lo de forma condicional, por exemplo {hasConsent && <Chatbot chatbotKey={key} />}, para carregar o chat só depois que o visitante aceitar o aviso de cookies.

  • 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 componente não precisa desfazer nada.
  • 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.
  • Mantenha o atributo. 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.

Opção 2: Uma tag script no index.html

Se você não precisa controlar o carregamento pelo código, pule o componente. 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>

  <!-- Nexoply AI chatbot -->
  <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.

Biblioteca de chatbot para React ou chatbot com IA hospedado

Quem procura um chatbot para React encontra dois tipos de ferramenta, e elas resolvem problemas diferentes:

  • Uma biblioteca de interface de chat oferece componentes React para o chat em si: lista de mensagens, campo de texto, balões e, às vezes, etapas de conversa predefinidas. Tudo o que fica por trás da interface é com você: roteiros fixos, ou um backend que chama um modelo de IA com a sua própria chave de API, além do conteúdo usado nas respostas, do armazenamento das conversas e da proteção contra abusos. Faz sentido quando o chat é parte do seu produto, por exemplo um assistente que trabalha com os dados dos seus usuários.
  • Um chatbot com IA hospedado como o Nexoply já traz a interface, a IA e o backend. Ele responde às perguntas dos visitantes só com as informações do negócio que você adiciona ou importa (serviços e preços, perguntas frequentes, políticas, horários) e avisa quando não sabe. Não há chave de IA nem código de servidor; as conversas, as perguntas sem resposta e a proteção contra spam ficam no painel. Faz sentido para um site voltado a clientes que precisa responder perguntas sobre o negócio.

Se você quer controle total sobre a interface e o modelo, comece com uma biblioteca. Se o objetivo é responder às perguntas dos visitantes sem construir nem manter um backend, o widget hospedado dá menos trabalho. Veja como o Nexoply responde com as informações do seu negócio.

Como ele se comporta em uma single-page app

  • Fica fora da árvore do React. O widget é montado em document.body, fora do seu elemento #root, então re-renderizações e mudanças de rota nunca o removem nem alteram o estilo dele.
  • Shadow DOM nos dois sentidos. Seu CSS (Tailwind, CSS modules, resets globais) não vaza para o chat, e o CSS dele não vaza para seu app.
  • Mudanças de rota funcionam sozinhas. Com React Router ou qualquer roteador 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.

Abra o chat pelo seu próprio botão

Quer um botão "Fale com a gente" no topo da 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"))}>
      Chat with us
    </button>
  );
}

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

Testes locais e solução de problemas

Antes de publicar, confira estes três pontos:

  • Sites permitidos. Se você preencheu Permitir apenas nestes sites (painel → Chatbot), adicione 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 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-a em Conversas no painel.

Se o botão ainda não aparecer:

  • Chave vazia. O componente não carrega nada sem chave. Exiba import.meta.env.VITE_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.

Próximos passos: personalize sem publicar de novo

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 imagem ou SVG próprio, texto, formato, tamanho, cores, posição) ou usa 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 como adicionar um chatbot ao Next.js com next/script ou o guia de chatbot para Vue e Nuxt; para um site em WordPress, o guia do WordPress. Para a visão completa, leia como o assistente aprende sobre seu negócio ou compare os planos e os limites de conversas.

Perguntas frequentes

Existe um componente simples de chatbot para React?

Sim: o componente <Chatbot /> deste guia, com menos de 20 linhas e um useEffect, que você copia para seu próprio projeto. Não há pacote npm oficial nem biblioteca de componentes para instalar, e você não precisa deles. O widget é sempre o script https://nexoply.com/widget.js com um atributo data-chatbot, e todas as configurações ficam no painel.

Funciona com React Router e outras navegações de SPA?

Sim. O widget mantém a conversa enquanto os visitantes navegam no lado do cliente e verifica de novo as regras de página quando a URL muda, sem código extra. Ele vive fora da árvore do React, então mudanças de rota nunca o removem.

Preciso de um backend ou de uma chave de API de IA?

Não. O Nexoply cuida da IA e do backend, e nenhuma chave de IA ou dado privado é enviado ao navegador. O único valor no seu código é a chave do chatbot, que é pública e não dá acesso à sua conta.

Ele deixa meu app mais lento?

Não de forma perceptível. O script carrega de forma assíncrona e nunca bloqueia a renderização, e roda dentro do próprio Shadow DOM sem mexer nos seus componentes.

Funciona com Next.js?

Sim, com o componente next/script no layout raiz. Veja o guia do Next.js para os trechos do App Router e do Pages Router.

Como escondo o chat em algumas rotas?

Não há API para removê-lo depois de carregado. Em vez disso, adicione uma regra de página com "Sem botão" (painel → Chatbot → Personalizar → Botão de mensagem → Diferente em algumas páginas), ou desligue o chatbot.

Deixe o seu site responder às perguntas por você

Adicione as informações do seu negócio, teste o seu assistente e coloque-o no seu site. Tudo isso no plano Grátis.