Como incorporar um chatbot em qualquer site

Você tem um chatbot treinado. Agora precisa colocá-lo no seu site. O Agentkit suporta quatro métodos de incorporação, e o certo depende da sua plataforma, da sua configuração técnica e de quanto controle você precisa. Este guia cobre as quatro opções com exemplos de código, detalhes de configuração e instruções específicas por plataforma.

Métodos de incorporação em resumo

A maioria dos usuários deve começar com o widget JS. Ele funciona em qualquer plataforma, carrega de forma assíncrona e leva menos de cinco minutos para configurar.

Antes de começar

Todo método de incorporação exige um chatbot treinado. Se você ainda não tem um:

1. Cadastre-se no Agentkit (gratuito).
2. Crie um chatbot e treine-o com o seu conteúdo usando URLs de site, documentos, pares de perguntas e respostas ou texto.
3. Teste-o no Playground até que as respostas estejam precisas.
4. Obtenha o seu código de incorporação em Configurações e depois Publicar no painel.

Para orientações sobre treinamento, veja Como treinar um chatbot com o conteúdo do seu site.

Método 1: widget JavaScript

O widget JS é o método universal de incorporação. Uma única tag de script, colocada antes da tag de fechamento </body>, carrega um balão de chat no seu site. Ele funciona em qualquer plataforma que permita JavaScript personalizado: sites HTML estáticos, plataformas de CMS, construtores de landing page e aplicações web.

Instalação básica

Copie esta tag de script e coloque-a antes da tag de fechamento </body> na sua página:

<script
  src="https://cdn.agentkit.ai/widget.js"
  data-chatbot="your-chatbot-id"
  async>
</script>

Substitua your-chatbot-id pelo ID real do seu painel do Agentkit. O atributo async garante que o script carregue sem bloquear a sua página.

Isso é tudo que você precisa para um chatbot funcional. O widget aparece como um balão de chat no canto inferior direito. Os visitantes clicam nele para abrir uma conversa.

Configuração via atributos de dados

Você pode personalizar o comportamento do widget adicionando atributos de dados à tag de script:

<script
  src="https://cdn.agentkit.ai/widget.js"
  data-chatbot="your-chatbot-id"
  data-position="bottom-right"
  data-theme="light"
  async>
</script>

Atributos de dados disponíveis

A maior parte da personalização visual (cores, mensagem de boas-vindas, marca) é controlada pelo painel do Agentkit, em vez de atributos de dados. Isso mantém o seu código de incorporação simples e permite atualizar as configurações sem alterar o código no seu site.

Como o widget carrega

O script do widget é leve e carrega de forma assíncrona. Veja o que acontece:

1. A sua página carrega normalmente. O atributo async significa que o script não bloqueia a renderização.
2. O script é baixado da nossa CDN e inicializado.
3. Um balão de chat aparece na página.
4. Quando um visitante clica no balão, a interface completa de chat carrega.
5. As mensagens são enviadas para a API do Agentkit e transmitidas de volta em tempo real.

O script inicial é pequeno. A interface completa de chat só carrega quando o visitante interage com o balão, então o impacto na velocidade da sua página é mínimo.

Instalação do widget por plataforma

O widget JS funciona em todas as plataformas, mas os passos para adicionar o script variam de acordo com a plataforma. Aqui estão links rápidos para os guias específicos de cada plataforma:

Método 2: componente React

Se você está construindo com React, Next.js, Remix ou Gatsby, o componente React oferece uma integração mais estreita do que a tag de script pura. Você ganha configuração baseada em props, tipos do TypeScript e a capacidade de interceptar eventos do chatbot.

Instalação

Instale o pacote React do Agentkit:

npm install @agentkit/react

Uso básico

import { AgentitkChat } from '@agentkit/react';

function App() {
  return (
    <AgentitkChat chatbotId="your-chatbot-id" />
  );
}

Isso renderiza o mesmo balão de chat do widget JS, mas como um componente React dentro da árvore de componentes do seu aplicativo.

Props

Integração com Next.js

Em um projeto Next.js com App Router, adicione o chatbot ao seu layout raiz para que ele apareça em todas as páginas:

// app/layout.tsx
import { AgentitkChat } from '@agentkit/react';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}
        <AgentitkChat chatbotId="your-chatbot-id" />
      </body>
    </html>
  );
}

Para o Pages Router, adicione o componente ao _app.tsx em vez disso.

Quando usar o componente React em vez do widget JS

Se você está usando React, use o componente React. Para tudo o mais, use o widget JS.

Método 3: iframe

O método de iframe incorpora o chatbot como uma página independente dentro de um frame no seu site. Isso é útil em ambientes onde a injeção de JavaScript é restrita ou onde você quer exibir o chatbot como um elemento inline, em vez de um balão flutuante.

Incorporação básica via iframe

<iframe
  src="https://cdn.agentkit.ai/embed/your-chatbot-id"
  style="width: 100%; height: 600px; border: none;"
  allow="clipboard-write">
</iframe>

Isso exibe a interface completa de chat de forma inline na sua página, não como um balão flutuante.

Quando usar iframe

Configuração do iframe

Personalize o iframe por meio de parâmetros de URL:

<iframe
  src="https://cdn.agentkit.ai/embed/your-chatbot-id?theme=dark"
  style="width: 400px; height: 600px; border: none; border-radius: 12px;"
  allow="clipboard-write">
</iframe>

Dimensionando o iframe

O iframe não se redimensiona automaticamente. Você controla as dimensões dele via CSS:

• Chat incorporado em largura total: width: 100%; height: 600px;
• Chat em barra lateral: width: 400px; height: 100vh; posicionado em um layout de barra lateral.
• Widget compacto: width: 350px; height: 500px; para uma área inline menor.

Limitações da incorporação via iframe

Para a maioria dos sites, o widget JS é a melhor escolha. Use o iframe apenas quando o widget JS não for uma opção ou quando você quiser especificamente uma experiência de chat inline.

Método 4: plugin do WordPress

Sites WordPress podem usar o widget JS por meio de qualquer um dos métodos descritos acima, mas também existe uma abordagem dedicada usando plugins de trechos de código que simplifica o processo para usuários sem conhecimento técnico.

Configuração rápida com o WPCode

1. Instale o plugin WPCode (gratuito, mais de 2 milhões de instalações) em Plugins e depois Add New.
2. Vá em Code Snippets e depois Header & Footer.
3. Cole a tag de script do Agentkit na seção Footer.
4. Salve.

O chatbot agora aparece em todas as páginas. O WPCode também suporta lógica condicional, então você pode mostrar o chatbot apenas em páginas específicas.

Outros métodos para WordPress

Para o passo a passo completo do WordPress com solução de problemas, veja Como adicionar um chatbot ao WordPress.

Opções de personalização

Independentemente do método de incorporação que você usa, a maior parte da personalização é feita pelo painel do Agentkit. Isso significa que você pode alterar as configurações sem mexer no seu código de incorporação.

Personalização visual

Personalização de comportamento

Considerações de segurança

Ao incorporar um chatbot no seu site, tenha estas configurações de segurança em mente.

Restrição de domínio

Sempre defina a restrição de domínio nas configurações do seu chatbot. Isso garante que o seu chatbot só carregue nos seus domínios autorizados. Sem ela, qualquer pessoa que encontrar o ID do seu chatbot poderia incorporá-lo no próprio site e usar a sua cota de mensagens.

Vá em Configurações no painel do Agentkit e adicione todos os domínios onde o chatbot deve funcionar:

• O seu domínio principal (por exemplo, yourbusiness.com)
• Quaisquer subdomínios (por exemplo, support.yourbusiness.com)
• Domínios de desenvolvimento ou staging, se você precisar testar

Limitação de taxa

A limitação de taxa restringe o número de mensagens que um único visitante pode enviar por sessão. Isso previne abusos e ajuda a controlar a sua cota de mensagens. Um limite de 15 a 25 mensagens por sessão é razoável para a maioria dos sites.

Content Security Policy

Se o seu site usa cabeçalhos de Content Security Policy, você precisa liberar os domínios do Agentkit. Adicione o seguinte ao seu CSP:

• script-src: cdn.agentkit.ai
• frame-src: cdn.agentkit.ai (se estiver usando o método iframe)
• connect-src: *.agentkit.com (para chamadas de API)

Solução de problemas comuns de incorporação

O chatbot não aparece

O chatbot aparece, mas não responde

• Verifique os dados de treinamento. Um chatbot não treinado não tem com o que trabalhar.
• Verifique o ID do chatbot. Um ID incorreto significa que o widget carrega, mas não consegue encontrar o chatbot.
• Verifique a restrição de domínio. Se o seu domínio não estiver na lista de permitidos, o chatbot não vai responder.
• Verifique a cota do seu plano. Se você usou todas as suas mensagens mensais, o chatbot vai parar de responder até o próximo ciclo de faturamento.

O chatbot entra em conflito com outros widgets

Se outro widget de chat (Intercom, Crisp, Drift) se sobrepuser ao seu, remova o outro widget, mude a posição do widget do Agentkit para bottom-left ou use o método iframe para colocar o chatbot de forma inline, em vez de como um balão flutuante.

Escolhendo o plano certo para a sua incorporação

O faturamento anual economiza aproximadamente 20% em todos os planos pagos. Comece com o plano Free para testar a incorporação e depois faça upgrade quando o seu tráfego exigir mais mensagens.

Próximos passos

Depois que o seu chatbot estiver incorporado, o trabalho muda da instalação para a otimização:

1. Monitore as conversas no painel do Agentkit durante a primeira semana. Identifique as perguntas com as quais o chatbot tem dificuldade.
2. Adicione dados de treinamento para os pontos fracos. Pares de perguntas e respostas são a forma mais rápida de corrigir problemas específicos de resposta.
3. Ative a captura de leads para coletar e-mails dos visitantes durante as conversas. Veja o guia de geração de leads.
4. Conecte-se às suas ferramentas via Zapier, webhooks ou a API REST. Veja o guia de integração.
5. Configure a restrição de domínio e a limitação de taxa para segurança e gestão de cota.

Para tutoriais passo a passo específicos de cada plataforma, veja os guias detalhados:

• WordPress
• Shopify
• Squarespace
• Wix
• Webflow

Crie seu chatbot gratuitamente →

Não é necessário cartão de crédito.