Tutoriais

Chatbot em Next.js: adicione um chatbot com IA com next/script (App Router e Pages Router)

Adicione um chatbot com IA a um app Next.js: um componente <Chatbot /> com next/script em app/layout.tsx ou pages/_app.tsx. Sem pacote npm, seguro com SSR.

Atualizado em 12 de novembro de 2026 8 min de leitura

Em resumo

Crie uma conta gratuita no Nexoply e copie a chave do seu chatbot na página Chatbot do painel. No App Router, adicione <Script src="https://nexoply.com/widget.js" data-chatbot={key} strategy="afterInteractive" /> do next/script dentro de <body> em app/layout.tsx; no Pages Router, coloque o mesmo <Script> em pages/_app.tsx. Não há pacote npm para instalar: o widget roda só no navegador, mantém a conversa durante a navegação no lado do cliente e não mexe no seu HTML, então não há problemas de hidratação.

  • Sem pacote npm: uma tag next/script, ou um pequeno componente <Chatbot /> que a envolve, no layout raiz (App Router) ou no _app (Pages Router).
  • Guarde a chave em NEXT_PUBLIC_NEXOPLY_KEY; ela é pública, não é um segredo e não dá acesso à sua conta.
  • Use strategy="afterInteractive" (a escolha padrão) ou "lazyOnload" para carregá-lo depois de todo o resto.
  • Compatível com SSR: roda só no navegador, é montado em um Shadow DOM no document.body e sobrevive às mudanças de rota.
  • Abra o chat pelo seu próprio botão com window.dispatchEvent(new Event("nexoply:open-chat")).

Antes de começar

  • Uma conta no Nexoply. Cadastre-se grátis: o plano Grátis inclui 50 conversas por mês, sem cartão.
  • As informações do negócio no Nexoply: 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 as geradas com JavaScript). 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.
  • A chave do seu chatbot. No painel, abra Chatbot (clique em Criar chatbot se ainda não criou). O código de instalação que aparece ali traz a chave no atributo data-chatbot.

Em um site HTML simples, o código de instalação seria colado antes de </body>:

<script src="https://nexoply.com/widget.js" data-chatbot="YOUR-KEY" async></script>

No Next.js você não edita o HTML diretamente, então adiciona o mesmo script com o componente nativo next/script. A chave é pública: ela só diz ao widget a qual negócio ele pertence.

App Router: adicione o script em app/layout.tsx

O layout raiz envolve todas as páginas, então adicionar o script ali coloca o chat no site inteiro. Importe Script de next/script e coloque-o dentro de <body>, depois de {children}:

// app/layout.tsx
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        {/* Nexoply chat widget: loads in the browser after hydration */}
        <Script
          src="https://nexoply.com/widget.js"
          data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Depois coloque a chave em uma variável de ambiente. O prefixo NEXT_PUBLIC_ faz o Next.js incluí-la no bundle do navegador, o que não tem problema aqui porque a chave não é um segredo:

# .env.local (not committed to git)
NEXT_PUBLIC_NEXOPLY_KEY=YOUR-KEY

Pages Router: adicione o script em pages/_app.tsx

No Pages Router, pages/_app.tsx envolve todas as páginas, então o mesmo <Script> vai ali, ao lado de <Component {...pageProps} />. Use a mesma variável do .env.local:

// pages/_app.tsx
import type { AppProps } from "next/app";
import Script from "next/script";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <Script
        src="https://nexoply.com/widget.js"
        data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
        strategy="afterInteractive"
      />
    </>
  );
}

Se seu projeto usa os dois routers, adicione o script tanto em app/layout.tsx quanto em pages/_app.tsx. Carregá-lo duas vezes não causa problema: o widget é montado uma única vez por chave de chatbot.

Opcional: um componente <Chatbot /> reutilizável

Prefere um componente <Chatbot />, como no guia do componente de chatbot para React? Mova o Script para um arquivo próprio. O next/script funciona em Server Components desde que você não passe handlers de eventos como onLoad, então este arquivo não precisa de "use client":

// components/Chatbot.tsx
import Script from "next/script";

export function Chatbot() {
  return (
    <Script
      src="https://nexoply.com/widget.js"
      data-chatbot={process.env.NEXT_PUBLIC_NEXOPLY_KEY}
      strategy="afterInteractive"
    />
  );
}

Depois renderize <Chatbot /> dentro de <body> em app/layout.tsx, depois de {children}, ou ao lado de <Component {...pageProps} /> em pages/_app.tsx. Renderize-o no layout, e não em uma página só, para que ele carregue em todas as rotas.

Escolher uma estratégia e como ele se comporta

strategy="afterInteractive" carrega o widget logo que a página fica interativa, então o botão de chat aparece rápido. strategy="lazyOnload" espera o navegador ficar ocioso e todo o resto carregar; escolha essa opção se quiser o primeiro carregamento o mais leve possível e não se importar que o botão apareça um instante depois. Nenhuma das duas coloca o script no caminho crítico de renderização. Veja a documentação do next/script para mais detalhes.

  • Navegação no lado do cliente. O widget mantém a conversa aberta enquanto os visitantes passam de uma página para outra com <Link> ou o roteador, e confere de novo suas regras de página quando a URL muda, sem código extra.
  • Seguro com SSR e hidratação. Roda só no navegador e é montado no document.body, fora do HTML que o React hidrata, então nunca causa erros de hidratação.
  • Shadow DOM. Seu CSS global ou do Tailwind não afeta o chat, e os estilos dele não afetam seu app. Novas renderizações nunca o removem.
  • StrictMode e Fast Refresh. Mesmo com efeitos rodando duas vezes em desenvolvimento ou hot reload, não surge um segundo chat: ele é montado uma vez por chave.
  • Armazenamento. Não usa cookies; usa localStorage para um identificador anônimo do visitante e sessionStorage para a conversa atual.

Criar seu próprio chatbot em Next.js ou usar um hospedado

Com Next.js é simples construir seu próprio chatbot, e às vezes essa é a escolha certa. As duas abordagens servem para trabalhos diferentes:

  • Construir você mesmo com uma biblioteca de interface de chat ou componentes próprios, mais um route handler ou uma rota de API que chama um modelo de IA com sua própria chave de API. O conteúdo usado nas respostas, o armazenamento das conversas e a proteção contra abusos também ficam com você. 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 e nada roda no seu 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, construa o seu próprio. Se o objetivo é responder às perguntas dos visitantes sem manter um backend, o widget hospedado dá menos trabalho. Veja como o Nexoply responde com as informações do seu negócio.

Abra o chat pelo seu próprio botão

Quer um botão "Fale com a gente" na seção principal ou de preços? Dispare o evento nexoply:open-chat em window. Como ele usa onClick, precisa ser um componente de cliente:

"use client";
// components/ChatButton.tsx

export function ChatButton() {
  return (
    <button
      type="button"
      // opens the Nexoply chat window
      onClick={() => window.dispatchEvent(new Event("nexoply:open-chat"))}
    >
      Chat with us
    </button>
  );
}

Use <ChatButton /> em qualquer página ou componente de servidor. Não há API para remover o widget depois de carregado: para esconder o botão de mensagem em algumas páginas (por exemplo /checkout), adicione uma regra de página com "Sem botão" em Chatbot → Personalizar → Botão de mensagem → Diferente em algumas páginas.

Teste local, sites permitidos e CSP

Rode next dev, abra http://localhost:3000 e um botão de chat aparece no canto. Faça uma pergunta real, como "Vocês atendem aos fins de semana?"; em segundos a conversa aparece em Conversas no seu painel. As mudanças que você faz no painel chegam ao site em cerca de um minuto, sem novo deploy.

Se seu app envia um cabeçalho Content-Security-Policy (por exemplo pelo middleware ou pelo next.config), libere o Nexoply em:

  • script-src https://nexoply.com: para carregar o widget.js.
  • connect-src https://nexoply.com: para as requisições do chat.
  • img-src https://nexoply.com: para imagens como o logo e o ícone do botão.

Solução de problemas e próximos passos

  • Sem botão, e data-chatbot vazio no código da página. A variável de ambiente não foi lida: confira o prefixo NEXT_PUBLIC_, reinicie o next dev e, na hospedagem, adicione a variável e faça um novo deploy.
  • O script está em uma página só, e não no layout. Coloque-o em app/layout.tsx ou pages/_app.tsx para carregar em todas as rotas.
  • A tag foi alterada. Ela precisa manter o atributo data-chatbot e um src que contenha widget.js.
  • Bloqueado pela CSP ou pelos sites permitidos. Procure erros no console do navegador e confira as duas seções acima.
  • Chatbot desligado. Verifique se a chave Chatbot ativado está ligada.
  • Bloqueadores de anúncios. Raramente, uma extensão bloqueia widgets de chat. Teste em uma janela anônima sem extensões.

Quando estiver funcionando, deixe-o com a cara do site em Chatbot → Personalizar: ícone, texto, cores e posição do botão, ou uma aba lateral na borda da tela (como "Ajuda"); um visual diferente no celular; e regras de página para páginas escolhidas (por exemplo, uma aba lateral só em /pricing). Veja todas as opções de personalização e como o assistente aprende sobre seu negócio, compare os planos e os limites de conversas ou leia o guia do componente de chatbot para React e o guia de chatbot para Vue e Nuxt.

Perguntas frequentes

Existe um componente de chatbot para React pronto para usar no Next.js?

Não há pacote npm oficial nem biblioteca de componentes, e você não precisa deles. O componente <Chatbot /> deste guia tem poucas linhas em volta do next/script e você o copia para seu projeto. O widget é sempre o script https://nexoply.com/widget.js com um atributo data-chatbot, e todas as configurações ficam no seu painel do Nexoply.

O chat continua durante a navegação no lado do cliente?

Sim. Os visitantes mantêm a conversa enquanto passam de uma página para outra com <Link> ou o roteador, e as regras de página são verificadas de novo quando a URL muda, sem código extra. O widget vive no document.body, fora dos seus layouts, então mudanças de rota nunca o removem.

Funciona na Vercel?

Sim. É só uma tag script carregada no navegador do visitante: nada roda no seu servidor, e não há rotas de API nem configurações de servidor para adicionar. Defina NEXT_PUBLIC_NEXOPLY_KEY nas variáveis de ambiente do seu projeto na Vercel e faça um novo deploy.

Afeta as Core Web Vitals ou o desempenho?

Ele foi feito para não afetar. O script carrega de forma assíncrona depois da hidratação (afterInteractive) ou quando o navegador fica ocioso (lazyOnload), então nunca bloqueia a renderização, e é montado fora do layout da sua página.

App Router ou Pages Router: qual devo usar?

O que seu projeto já usa; o widget funciona igual nos dois. App Router: app/layout.tsx. Pages Router: pages/_app.tsx.

Posso carregá-lo só depois do consentimento de cookies?

Sim. Renderize o <Script> só depois que o visitante aceitar, por exemplo em um componente de cliente que verifique seu estado de consentimento. O widget em si não usa cookies.

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.