Your AI Connector Docs

Widget de Chat

Guia de Integração do Widget de Chat no Site

Adicione um widget de chat amigável ao seu site que permite aos visitantes se comunicarem diretamente através da interface do seu site. O processo de integração é simples e fornecerá ao seu site recursos de mensagens integrados.

Criando e configurando o widget de chat

Como chegar lá:

  1. Clique em Configurações perto da parte inferior da barra lateral esquerda. (Em um celular, primeiro toque no ícone de menu ☰ no canto superior para abrir a barra lateral.)
  2. Na barra lateral de Configurações, em Canais, clique em Canais.
  3. Encontre o cartão Widget de chat do site.
  4. Se você ainda não tiver um widget, clique em Conectar para criar um com um nome de exibição e uma mensagem de boas-vindas.
  5. Depois de criado, clique em Gerenciar a qualquer momento para abrir o painel de configuração completo.

As alterações que você salva são aplicadas ao seu widget ativo automaticamente — não há necessidade de colar o código de instalação novamente após fazer uma alteração.

Uma Prévia ao vivo fica bem ao lado das configurações: uma página da web de exemplo com seu widget real em execução, mostrando suas cores, posição, logotipo, ícone do iniciador e pop-up proativo exatamente como os visitantes os verão. Ela segue suas edições conforme você as faz, para que você não precise salvar para ver como fica uma alteração de cor ou tema. Você pode até clicar no botão de chat dentro da prévia para abrir o widget e experimentá-lo.

O que você pode personalizar

O painel Gerenciar é organizado em quatro seções.

Aparência

  • Tema de estilo: Redesenhe todo o widget com um clique. Seis temas definem a aparência, cores, cantos e fonte de uma só vez: Classic (o visual sólido original — uma barra de cabeçalho colorida em um painel plano), Glass (um painel fosco e translúcido que desfoca suavemente a página atrás dele, com o cabeçalho e a caixa de mensagem flutuando como cartões arredondados dentro dele), Midnight (Glass em cores escuras), Bloom (rosa suave, extra-arredondado), Ember (Glass em laranja quente) e Mono (preto e branco, cantos vivos). Um tema é um ponto de partida — após escolher um, você ainda pode alterar qualquer cor ou ajuste individualmente. Novos widgets começam no Glass; a troca é instantânea onde quer que o widget esteja incorporado, sem alterações de código no seu site.
  • Cantos e Fonte: Dois ajustes de estilo independentes. Cantos define o quão arredondados são o painel, os balões e os botões (Arredondado, Suave ou Vivo), e Fonte escolhe o tipo de letra que os visitantes veem (Padrão, Serif, Arredondado ou Mono) — as fontes vêm do que já está no dispositivo do visitante, então nada extra é carregado no seu site.
  • Nome de exibição: Exibido no cabeçalho do widget.
  • Logotipo: Faça upload de uma imagem que aparece no topo do chat. Use o logotipo da sua empresa ou uma foto amigável.
  • Ícone do iniciador: O ícone no próprio botão de chat flutuante. Escolha um dos ícones integrados (balão de chat, avião de papel, ponto de interrogação e mais), reutilize seu logotipo enviado ou faça upload de uma imagem separada — útil se você quiser uma foto de um membro real da equipe cumprimentando os visitantes.
  • Cores: Cinco cores, cada uma nomeando a parte do widget que ela pinta. Cor da marca é o botão flutuante, o cabeçalho e as mensagens do próprio visitante, com Texto da marca para o texto que fica sobre ela. Balão do bot é o fundo das respostas do seu bot e do indicador de digitação, com Texto do balão do bot para as palavras dentro deles e os pontos de digitação animados. Janela de chat é o painel atrás de todas as mensagens. Escolha uma cor para o balão do bot que seja claramente diferente da cor da sua marca — se as duas coincidirem, ambos os lados da conversa ficarão com a mesma cor e os visitantes não conseguirão distinguir as respostas do seu bot das deles. Um balão de bot cinza claro com texto escuro ao lado da cor da sua marca é a combinação segura.
  • Posição: Coloque o botão de chat flutuante no canto inferior direito ou inferior esquerdo, com deslocamento horizontal e vertical (em pixels) caso ele se sobreponha a algo na sua página.
  • Perguntas iniciais: Sugestões de resposta rápida (chips clicáveis) exibidas no chat para que os visitantes possam começar com um toque em vez de digitar — por exemplo, “Quais são seus preços?” ou “Vocês oferecem suporte?” — até 10.
  • Linha de rodapé: Uma pequena linha opcional com seu próprio texto abaixo da caixa de mensagem, por exemplo, “Desenvolvido por Sua Agência”. Ela fica desativada por padrão, e nada é exibido abaixo da caixa de mensagem enquanto estiver desativada. Ative-a, digite seu texto (até 40 caracteres) e, se desejar, adicione um link começando com https://; os visitantes que clicarem no texto abrirão essa página em uma nova aba. Agências a utilizam para colocar seu próprio nome nos widgets que criam para clientes.

Comportamento

  • Mensagem de abertura: A primeira mensagem que os visitantes veem ao abrir o chat (por exemplo, “Como posso ajudar?”).
  • Som: Reproduz um som quando uma nova mensagem chega no chat.
  • Solicitar permissão de notificação: Opcionalmente, peça aos visitantes que permitam notificações do navegador, para que sejam alertados sobre respostas mesmo quando mudarem de aba.
  • Balão de popup proativo: Um pequeno balão opcional que aparece ao lado do botão de chat para convidar as pessoas. Ative-o para definir sua mensagem, o texto dos botões de aceitar/recusar e quantos segundos aguardar antes que ele apareça. O balão fecha sozinho após 20 segundos se o visitante não clicar nele. É o único texto que o widget exibe ao lado do botão de chat: não há configuração para um rótulo permanente ao lado do botão.
  • Velocidade de resposta da IA: Um controle deslizante entre Mais lenta (mais humana — a IA leva um tempo antes de responder) e Velocidade máxima (mais robótica — as respostas chegam o mais rápido possível). O modo Equilibrado fica no meio. A primeira mensagem de uma resposta chega com o atraso definido pelo controle deslizante, com o indicador de digitação aparecendo pouco antes.
  • Mostrar uma nota de ocupado enquanto a IA trabalha: Desativado por padrão. Quando uma resposta leva mais do que alguns segundos, por exemplo, porque seu agente está procurando algo em outro sistema, os visitantes veem uma linha curta ao lado dos pontos de digitação: “Trabalhando na sua resposta” após 5 segundos, “Procurando isso para você” após 15, depois “Ainda nisso, quase lá” e um pedido de desculpas pela espera se demorar mais. Respostas rápidas mostram apenas os pontos. A linha segue o idioma do widget e só aparece enquanto sua IA está realmente trabalhando em uma resposta, nunca quando a IA está desligada para aquele chat ou uma pessoa assumiu o atendimento.

Idiomas

O widget é multilíngue por padrão — não há nada para ativar.

  • Ele escolhe o idioma do visitante automaticamente. Primeiro, ele verifica o idioma que sua página declara no HTML (<html lang="it">) e, em seguida, recorre ao idioma do navegador do visitante. Se nenhum dos dois for um idioma que suportamos, os próprios rótulos do widget são exibidos no idioma em que você escreveu sua mensagem de abertura, e sua mensagem de abertura, balão de pop-up e perguntas iniciais aparecem exatamente como você os escreveu.

  • Um idioma de página que contradiz sua saudação não é confiável. Alguns construtores de sites colocam lang="en" em todas as páginas, independentemente do idioma do site. Quando a página declara um idioma e você escreveu sua mensagem de abertura em outro, o widget trata o valor da página como um padrão do construtor: ele segue o idioma do navegador do visitante e, se esse não for um idioma que suportamos, ele usa o idioma em que você escreveu. Uma página que alterna seu valor de lang quando o visitante escolhe um idioma em seu site é sempre seguida. Se você preferir não depender de nada disso, fixe o idioma na seção Comportamento.

  • Ou escolha você mesmo. O campo Idioma do widget na seção Comportamento é definido como Automático por padrão, que é a detecção acima. Escolha um idioma lá e os próprios rótulos do widget (campos Nome, E-mail e Telefone do formulário do visitante e seu texto de exemplo, o aviso de privacidade, os botões) permanecerão nesse idioma, independentemente do que a página ou o navegador digam. Use isso quando seu construtor de sites não declarar o idioma correto ou quando você quiser um idioma fixo para todos os visitantes.

  • Idiomas suportados: Inglês, Holandês, Alemão, Francês, Espanhol, Italiano, Português, Romeno, Polonês, Árabe, Finlandês, Filipino, Esloveno, Tailandês, Bengali, Japonês, Norueguês (Bokmål) e Turco. Esta é a lista para os botões e rótulos do próprio widget.

  • Idiomas da direita para a esquerda são dispostos da direita para a esquerda. Para visitantes que usam Árabe, Hebraico, Persa e Urdu, toda a janela de chat é espelhada: o cabeçalho, os balões de mensagem, os pontos de digitação, o formulário do visitante e a caixa de mensagem começam pela direita. O botão do balão permanece no canto que você escolheu. Visitantes que usam Hebraico, Persa e Urdu veem os rótulos em Inglês (ou no idioma que você fixou), mas o layout ainda segue o idioma deles. Uma mensagem escrita em uma direção diferente, como uma resposta em Inglês em um chat em Árabe, ainda é lida na ordem correta.

  • Suas mensagens são traduzidas para você. Toda vez que você salva, sua mensagem de abertura, balão de pop-up proativo e perguntas iniciais são traduzidos para todos os dezoito idiomas acima. Você só precisa escrevê-los uma vez, no idioma que preferir: o idioma em que você escreveu é reconhecido pelo próprio texto, essa versão é mantida palavra por palavra e todos os outros idiomas são uma tradução dela. Não importa em qual idioma sua conta está configurada.

  • Escreva sua própria versão para um idioma. A seção Traduções do painel Gerenciar, logo abaixo de Comportamento, permite que você substitua a tradução automática pelo seu próprio texto, por exemplo, Espanhol formal (“usted”) onde a tradução automática é informal. Escolha um idioma em Idioma e preencha qualquer um dos campos: Mensagem de abertura, Mensagem de pop-up, Texto de aceitação e Texto de recusa do pop-up (exibidos enquanto o balão de pop-up está ativo) e Perguntas iniciais. Cada campo mostra a tradução automática em cinza; Começar a partir da tradução automática copia o texto para que você possa editá-lo a partir daí. Qualquer campo que você deixar em branco manterá a tradução automática. Os idiomas que você mesmo escreveu são listados primeiro, marcados como Seu próprio texto, e Remover meu texto em (idioma) retorna à tradução automática para aquele idioma. Seu próprio texto é mantido quando você edita o texto original posteriormente; apenas as traduções automáticas são refeitas.

  • Os botões de pop-up também são traduzidos. Os botões Aceitar e Recusar do balão de pop-up proativo são traduzidos junto com suas outras mensagens, para que um visitante espanhol não veja mais botões em Inglês.

  • Escreva cada mensagem em apenas um idioma. Se você colocar dois idiomas no mesmo campo — uma linha em Inglês e uma linha em Italiano, por exemplo — tudo será tratado como uma única mensagem e traduzido como está, de modo que um visitante italiano acabará vendo a mesma frase duas vezes. Escreva uma vez, no idioma que preferir.

  • A IA responde no idioma do visitante. Independentemente do idioma em que alguém digita, seu agente responde nesse mesmo idioma, independentemente de qual idioma os rótulos do widget estejam exibindo. Se você preferir que ele sempre responda em um idioma fixo, especifique isso nas instruções do seu agente.

  • Defina o idioma por página no código de incorporação. Executando um widget em um site em inglês e uma cópia traduzida dele? Adicione data-lang à tag de script do widget em cada página. data-lang="es" exibe o widget em espanhol nessa página, independentemente do que o navegador diga; data-lang="page" faz com que ele siga o valor <html lang="..."> da própria página (portanto, lang="es-MX" resulta em espanhol), mesmo quando sua mensagem de abertura estiver escrita em outro idioma. Isso tem prioridade sobre o campo Idioma do widget, que por sua vez tem prioridade sobre a detecção automática. Por exemplo:

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" data-lang="page" defer></script>

Mantenha o código de incorporação do painel Gerenciar como está e adicione apenas o atributo data-lang. Para um painel de chat embutido, coloque data-lang no <div data-chat-widget="…"> em vez disso.

Dica: se o seu site não define um atributo lang na tag <html>, adicione um. É o sinal mais forte que temos para escolher o idioma correto, especialmente para visitantes que navegam do exterior.

Captura de leads e privacidade

  • Coletar informações do visitante: Desativado por padrão. Quando ativado, os visitantes são solicitados a informar seu nome e e-mail (e opcionalmente telefone) antes que a conversa comece, para que você capture o lead mesmo que eles saiam no meio do chat.
  • Título do formulário e Subtítulo do formulário: Personalize o cabeçalho e a breve explicação exibidos acima do formulário.
  • Coletar número de telefone: Ative para solicitar também um número de telefone; desativado, coleta apenas nome e e-mail.
  • Coletar sobrenome: Desativado por padrão. Ative para adicionar um campo obrigatório de Sobrenome logo após o Nome. Ele é salvo no contato como o sobrenome, para que sua IA e qualquer coisa que ela consulte em seus próprios sistemas tenha o nome completo desde a primeira mensagem. Visitantes que já preencheram o formulário antes de você ativar isso não serão solicitados novamente.
  • E-mails de resposta não lida para visitantes: um visitante que deixou um endereço de e-mail e não viu sua resposta após 15 minutos recebe um e-mail direcionando-o de volta ao chat. Desative em Configurações → Notificações → Visitantes do widget de chat. Veja E-mails para visitantes do widget de chat.

Um visitante deixou um número de telefone e saiu do seu site — posso continuar no WhatsApp? Sim. Abra o chat dele e escolha Continuar no WhatsApp no menu de três pontos (o WhatsApp Web ou WhatsApp Business precisa estar conectado). O Your AI Connector cria uma conversa vinculada no WhatsApp para a mesma pessoa, copia seu nome, e-mail e detalhes, e a IA transfere o que foi dito no seu site, para que ninguém precise repetir nada. O chat do site permanece onde está e ambos os chats apontam um para o outro em Conversas vinculadas no painel de contato. Veja Interface de Chat.

Um visitante deixou seu e-mail e não reservou — posso fazer um acompanhamento por e-mail? Sim, com uma automação. Uma etapa Criar contato com o Canal definido como E-mail transforma o endereço que o visitante deixou em um contato de e-mail no seu Canal de e-mail conectado, e uma etapa Enviar mensagem logo após é enviada como um e-mail; as respostas retornam para Chats para o seu agente de e-mail. A receita completa, incluindo como interromper a sequência assim que eles informarem que reservaram, está em Automações → Exemplo: acompanhamentos por e-mail para leads de chat do site.

O agente de IA pode oferecer a mudança para o WhatsApp por conta própria? Sim, e não precisa de nenhum recurso extra — uma linha nas instruções do agente resolve isso. Crie um Link Curto para o seu número de WhatsApp com uma mensagem preenchida, como “Olá, eu estava conversando no seu site e quero continuar por aqui”, então diga ao agente quando enviá-lo, por exemplo: “Se o visitante precisar sair, quiser continuar mais tarde ou pedir pelo WhatsApp, ofereça continuar por lá e envie este link: (seu link curto)”. Links no widget são clicáveis, então o visitante chega ao WhatsApp com seu número selecionado e a mensagem pré-digitada, e a primeira mensagem dele abre uma conversa no WhatsApp na sua caixa de entrada. Se o visitante deixou o número de telefone do qual escreve (com código do país) no formulário do widget, o Your AI Connector vincula as duas conversas automaticamente e a IA no WhatsApp já conhece o chat do site, exatamente como em Continuar no WhatsApp. Se nenhum número de telefone foi coletado, os dois chats não são vinculados, portanto, mantenha a mensagem preenchida específica o suficiente para que o agente do WhatsApp saiba de onde a pessoa veio.

  • Exigir reconhecimento da política de privacidade: Opcionalmente, exija que os visitantes aceitem sua política de privacidade antes de conversar e defina a URL para a qual ela aponta.

O que o widget armazena no navegador do visitante e preciso colocá-lo atrás de um banner de cookies? Nada é armazenado apenas pelo carregamento de uma página. O widget não grava cookies nem usa armazenamento do navegador até que o visitante escolha conversar: envie uma primeira mensagem, preencha o formulário de informações do visitante ou aceite sua política de privacidade. A partir desse momento, ele mantém um ID de conversa aleatório e uma cópia da conversa naquele navegador, como armazenamento primário (first-party) em seu próprio domínio, para que o chat ainda esteja lá quando o visitante retornar. Ele não carrega scripts de análise ou rastreamento e não define cookies de terceiros. Como nada é gravado até que o visitante solicite o chat, isso se enquadra no armazenamento estritamente necessário para um serviço solicitado pelo visitante, portanto, você pode carregá-lo sem bloqueá-lo atrás de um banner de consentimento. Se o seu site usa uma ferramenta de consentimento de qualquer maneira, não há problema em manter o widget atrás dela; o chat simplesmente aparecerá assim que o visitante aceitar.

Canais e incorporação

  • Botão de anexo: Permite que os visitantes enviem imagens e arquivos no chat.
  • Seletor de emojis: Adiciona um seletor de emojis ao lado da caixa de mensagem.
  • Links de canais: Opcionalmente, inclua links do WhatsApp, Instagram ou Messenger para que os visitantes possam continuar a conversa na plataforma que preferirem. Isso só aparece depois que você conecta um número de WhatsApp (WhatsApp Business ou WhatsApp Web), Instagram ou Messenger. Ativar o link do WhatsApp preenche o seu número conectado; o link permanece editável, então, após alterar os números, você pode digitar o novo lá.
  • Botões de ação: Uma linha de atalhos na parte superior do chat que levam o visitante a algum lugar em vez de iniciar uma conversa — veja Botões de ação abaixo.
  • Lista de permissão de domínio: Restrinja quais sites têm permissão para incorporar seu widget. Adicione os domínios onde você o instalou (por exemplo, example.com ou *.example.com); deixe vazio para permitir qualquer domínio.
  • Países bloqueados: Mantenha o widget longe de visitantes em países que você não atende. Visitantes cuja localização de rede esteja em um país que você escolher nunca verão o widget, e qualquer chat que tentarem iniciar será recusado. Deixe vazio para permitir todos. Veja Mantendo bots e consumo de créditos fora abaixo.
  • Encaminhar estes chats para: Escolha o agente que deve lidar com os chats provenientes do código que você está prestes a copiar. Deixe em Padrão da conta para usar o roteamento normal do seu widget de chat. Veja Enviar páginas diferentes para agentes diferentes abaixo.
  • Snippet de incorporação: Escolha Bolha flutuante ou Em linha e copie o código de instalação (veja abaixo).
  • Link de demonstração para cliente: Cole qualquer endereço de site e clique em Criar link para obter um link compartilhável que abre esse site com seu widget rodando sobre ele, sem nada para instalar do lado deles. Cada link que você cria é listado, e você pode desativar cada um deles. Veja Mostrar o widget no site de outra pessoa abaixo.
  • Link de compartilhamento: Um link pronto que abre seu assistente em uma página própria, em tela cheia, sem necessidade de um site. Copie-o e envie para qualquer lugar. Veja Compartilhar um link direto para o chat abaixo.

Na parte inferior do painel, uma ação Excluir widget de chat remove o widget do seu site imediatamente — isso não pode ser desfeito e os visitantes não verão mais o balão de chat.

Botões de ação

Alguns visitantes não querem conversar. Eles querem seu número de telefone, seu endereço ou seu e-mail, e querem isso com um toque. Os botões de ação são uma linha de atalhos na parte superior do painel de chat exatamente para isso.

Adicione até seis. Cada um tem um rótulo (as palavras no botão) e um destino, e o destino depende da ação que você escolher:

Ação O que o visitante recebe O que você preenche
Ligar O discador de telefone deles abre com seu número pronto Seu número de telefone, ex: +1 555 123 4567
Enviar SMS O aplicativo de mensagens deles abre um novo texto para você Seu número de telefone
WhatsApp O WhatsApp abre um chat com você Seu número de WhatsApp ou um link wa.me que você já possui
E-mail O aplicativo de e-mail deles abre um novo e-mail para você Seu endereço de e-mail
Direções O Google Maps abre com sua localização Seu endereço ou um link de mapas que você já possui
Link A página abre em uma nova guia Qualquer endereço da web completo começando com https://

Estes botões não usam créditos. Tocar em um não envia uma mensagem e não inicia uma conversa — ele apenas leva o visitante para onde ele pediu para ir. Apenas uma conversa real com seu agente de IA usa créditos, exatamente como antes.

Algumas coisas que vale a pena saber:

  • Os botões permanecem visíveis enquanto o visitante conversa. Alguém pode fazer duas perguntas e ainda tocar em Direções depois, sem recarregar a página.
  • Seus rótulos são exibidos exatamente como você os escreveu. Ao contrário da sua mensagem de boas-vindas e perguntas iniciais, os rótulos dos botões não são traduzidos automaticamente, portanto, se você atende visitantes em vários idiomas, mantenha os rótulos curtos e óbvios (ou escreva-os no seu idioma principal).
  • Preencha um botão corretamente ou ele não será salvo. Se um número de telefone, endereço de e-mail ou link não for válido, o painel informará isso e bloqueará o botão Salvar alterações em vez de publicar um botão que não faria nada em seu site.
  • Eles não são respostas de FAQ. Os botões de ação apenas enviam as pessoas para outro lugar; eles não respondem com texto pronto. Perguntas são trabalho do seu agente de IA, e ele as responde a partir da sua base de conhecimento. Se você quiser sugerir o que perguntar, use perguntas iniciais em Aparência.

O que você não pode personalizar

O painel Gerenciar é o conjunto completo de opções. Em particular:

  • Sem CSS ou folha de estilo personalizada. O estilo é definido pelo que o tema, os seletores de canto, fonte e cor oferecem — você não pode injetar seu próprio CSS no widget, e as regras da sua página não afetarão o conteúdo dele.
  • Sem texto de placeholder personalizado na caixa de mensagem.
  • Sem incorporação de vídeo dentro do chat.

Se um desses pontos for um impedimento para você, a incorporação inline oferece o maior controle: o widget fica em um contêiner na sua própria página, que você dimensiona e posiciona como desejar.

Mantendo Bots e Consumo de Créditos Fora

Cada resposta de IA custa créditos, então um script (ou uma pessoa entediada) abrindo chat após chat no seu site é a única coisa contra a qual um widget público precisa se defender. O widget lida com a maior parte disso sozinho, e duas configurações no painel Gerenciar permitem que você reforce isso para o seu site.

  • Lista de permissões de domínio. Apenas os sites que você listar podem exibir o widget. Qualquer pessoa que copiar seu código de incorporação para outro site não verá nada.
  • Países bloqueados. Visitantes cuja localização de rede esteja em um país que você bloqueou nunca verão o widget, e um chat que eles tentarem iniciar será recusado. A localização vem da conexão do visitante: alguém em uma VPN aparece como sendo do país da VPN, e um visitante cuja localização não pode ser determinada é permitido em vez de bloqueado. Sua própria visualização dentro do aplicativo continua funcionando mesmo se você bloquear o país em que está.
  • Novas conversas por conexão. Uma conexão (na prática, um endereço residencial ou comercial) pode abrir 20 novas conversas por dia em um widget. Visitantes recorrentes que continuam seu chat existente não contam, apenas conversas totalmente novas contam, então um script que continua iniciando chats novos para obter respostas de IA esgota o limite após 20, enquanto visitantes reais nunca percebem. Se muitas pessoas compartilham uma conexão em seu site (um campus, um call center), aumente o número através da REST API com max_new_chats_per_ip_daily; 0 desativa a verificação.
  • Verificação humana (opcional). Os visitantes passam por uma verificação rápida do Cloudflare Turnstile antes que sua primeira mensagem seja enviada, para que um script não possa iniciar chats. A maioria das pessoas nunca clica em nada; o Cloudflare só mostra uma caixa de seleção quando não tem certeza. Ele usa suas próprias chaves gratuitas do Turnstile, veja Adicionar uma verificação humana abaixo.
  • Limites integrados. Além disso, cada sessão de navegador é limitada em quantas mensagens pode enviar por minuto e por dia, e o agente que responde ao chat para de responder a um visitante assim que ele atinge o Máximo de mensagens de IA por chat definido em seus Limites de resposta.

Nada disso identifica dispositivos ou pessoas: o widget não armazena nada no navegador do visitante até que ele escolha conversar (veja acima), e não há fingerprinting.

Adicionar uma verificação humana (Cloudflare Turnstile)

Ative isso quando bots continuarem abrindo chats em seu site e as configurações acima não forem suficientes. A verificação é executada uma vez, logo antes da primeira mensagem de um visitante ser enviada. Um visitante que passar pode continuar conversando por 24 horas sem vê-la novamente, e qualquer pessoa que retornar a uma conversa anterior ainda pode lê-la antes da verificação.

  1. Entre na sua conta Cloudflare (uma conta gratuita é suficiente) e abra o Turnstile.
  2. Clique em Add widget, dê um nome a ele e adicione todos os domínios em que seu widget de chat é executado (por exemplo, yourshop.com). Deixe o modo do widget em Managed.
  3. Copie a Site key e a Secret key que o Cloudflare mostrar para você.
  4. No aplicativo, abra o painel Manage do seu widget de chat, ative Human check before chatting, cole ambas as chaves e salve.

O que esperar:

  • A verificação permanece desativada até que ambas as chaves sejam preenchidas, portanto, ativá-la sem as chaves nunca bloqueia os visitantes.
  • Se um visitante falhar na verificação ou deixá-la sem solução, sua mensagem não será enviada e ele receberá um botão Retry.
  • A verificação só aparece nos domínios que você adicionou no Cloudflare. Em qualquer outro domínio, o Cloudflare a recusa e ninguém nesse site pode enviar uma mensagem, portanto, adicione todos os domínios antes de ativá-la.
  • Se o seu site usa uma Política de Segurança de Conteúdo (Content Security Policy), permita https://challenges.cloudflare.com para scripts e frames, ou a verificação não poderá ser carregada.
  • As chaves são da sua própria conta Cloudflare, e a chave secreta nunca é enviada para os navegadores dos seus visitantes.

Instruções de Instalação

Para adicionar o widget de chat ao seu site, adicione uma linha de código ao HTML do seu site.

  1. Abra o arquivo HTML do seu site em um editor de texto.
  2. Encontre a tag de fechamento </body> — geralmente ela fica bem no final do arquivo.
  3. Cole esta linha de código logo antes da tag </body>, para que o restante da sua página seja carregado primeiro:
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>
  1. Substitua CONFIG_ID pelo seu identificador de configuração exclusivo, exibido na seção Canais e Incorporação (Channels & Embed) do painel Gerenciar. Este identificador é específico para sua conta e conecta o widget ao seu sistema de mensagens.

O snippet não deixará seu site lento: é um carregador minúsculo, e o próprio widget é baixado em segundo plano sem bloquear a página. Se você ainda quiser que o widget aguarde até que sua página termine de carregar completamente, você pode envolver a mesma URL desta forma:

<script>
window.addEventListener('load', function () {
  var s = document.createElement('script');
  s.src = 'https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID';
  s.async = true;
  document.body.appendChild(s);
});
</script>

E se o que você deseja atrasar é o pequeno balão de convite em vez do carregamento do widget, esse é o atraso do Balão de pop-up proativo na seção Comportamento acima — sem necessidade de código.

Instalando no Shopify

  1. No seu admin do Shopify, vá para Loja virtual > Temas.
  2. No tema marcado como seu tema atual (publicado), clique no botão … e escolha Editar código. Editar um rascunho ou uma cópia do tema não altera nada na sua loja ativa.
  3. Abra layout/theme.liquid e role até a tag de fechamento </body> perto do final.
  4. Cole sua linha de instalação logo acima de </body> e clique em Salvar:
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

Se você instalou o widget antes de a linha de instalação conter defer, o editor de código do Shopify mostrará um sublinhado vermelho abaixo dela. Esse sublinhado é um aviso do verificador de código do Shopify sobre linhas de script sem defer ou async, não um erro: o tema ainda salva e o widget ainda funciona. Adicionar defer como mostrado acima faz o sublinhado desaparecer e não altera nada em como o widget se comporta, portanto, não há necessidade de reinstalar em outros sites.

Aqui está um exemplo completo de como seu arquivo HTML deve ficar com o widget de chat implementado:

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>
<body>
    <!-- Your existing website content would be here -->

    <!-- Chat Widget Integration -->
    <script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>
</body>
</html>

Incorporar em Linha em uma Página (Avançado)

Se você preferir que o chat apareça como parte da sua página — por exemplo, dentro de uma seção dedicada de “Fale conosco”, uma aba de ajuda ou uma barra lateral — em vez de um balão flutuante no canto, altere Snippet de incorporação (Embed snippet) para Em linha (Inline) no painel Gerenciar e copie o snippet em linha.

Fica assim:

<div data-chat-widget="CONFIG_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

O <div> é o ponto de montagem — o painel de chat é renderizado dentro dele e preenche suas dimensões. Estilize a div como quiser (dê a ela uma altura fixa, coloque-a dentro de um container flex, posicione-a em uma célula de grid, etc.) e o painel de chat seguirá essas definições.

Você só precisa de uma tag <script> na página, mesmo que esteja incorporando vários widgets de chat. O script verifica a página em busca de cada <div data-chat-widget="…"> e monta um painel de chat em cada um.

Quando escolher entre inline ou flutuante:

  • O balão flutuante é ideal para um botão “Precisa de ajuda?” sempre disponível em todo o site.
  • A incorporação inline é ideal quando o chat deve ficar em um lugar específico — uma página de suporte, uma barra lateral de base de conhecimento, uma aba de ajuda no aplicativo — e parecer uma parte nativa daquela página.

A incorporação em linha reutiliza a mesma configuração do balão flutuante (logotipo, mensagem de abertura, captura de leads, perguntas iniciais, etc.), para que você não precise configurar nada duas vezes.

Mostrar o Widget no Site de Outra Pessoa

Você pode mostrar seu widget de chat rodando em um site que você não controla — sem necessidade de código ou acesso ao site deles. É a maneira mais rápida de mostrar a um cliente em potencial como o assistente ficaria nas páginas dele.

  1. Abra o painel Gerenciar e role até Canais e Incorporação.
  2. Em Link de demonstração do cliente, digite o endereço do site (por exemplo, www.theircompany.com).
  3. Opcional: abaixo do campo, escolha o Agente que deve responder nesta demonstração, por exemplo, um agente que você criou a partir do próprio site do cliente potencial para que ele fale sobre seus serviços, preços e perguntas frequentes. Deixe em Padrão da conta para usar o roteamento normal do seu widget de chat.
  4. Clique em Criar link. O link é copiado para você e aparece na lista abaixo do campo, com botões Copiar e Abrir e o agente que ele utiliza.
  5. Envie o link para quem você quiser mostrar.

Abrir o link carrega esse site com seu widget de chat flutuando sobre ele, exatamente como pareceria se estivesse instalado. Qualquer pessoa com o link pode abri-lo — não há nada para fazer login.

Algumas coisas que vale a pena saber:

  • Os chats da demonstração são reais. As mensagens que um visitante envia em uma demonstração chegam à sua caixa de entrada e são respondidas pelo seu agente, e elas consomem créditos como qualquer outra conversa.
  • A página não possui marca. Ela mostra o site deles e seu widget, e nada mais.
  • Alguns sites não podem ser exibidos em frames. Vários sites (bancos, grandes varejistas, qualquer coisa protegida por configurações de segurança rígidas) impedem que outras páginas os exibam. Quando isso acontece, o link ainda funciona: ele mostra uma janela de navegador simulada neutra em vez do site real, com seu widget ativo sobre ela, para que a demonstração ainda cumpra seu papel.
  • Isso não altera o site deles. Nada é instalado e nada é modificado — a demonstração existe apenas dentro daquele link.
  • Desative um link quando a demonstração terminar. Clique em Desativar ao lado do link na lista e confirme. A partir de então, qualquer pessoa que abri-lo verá uma página informando que o link foi desativado. Seu widget e seus outros links de demonstração continuam funcionando. Um link que foi desativado não pode ser reativado; crie um novo em vez disso.
  • Links copiados antes de 25 de setembro de 2026. Links de demonstração criados antes da existência da lista não estão nela. Eles continuam funcionando até que você clique em Desativar todos abaixo da lista, o que desativa todos de uma vez (e Reativar todos reverte isso).

Um link de demonstração criado sem um agente usa o roteamento padrão da sua conta, independentemente do que esteja definido em Encaminhar estes chats para. Com um agente selecionado, cada chat desse link é atribuído a esse agente e respondido por ele. O widget mantém sua própria aparência, nome e mensagem de abertura. O link o carrega como &agent=AGENT_ID; adicionar isso manualmente a um link antigo também funciona (use &, não ?, porque o link já contém um ?).

Se você excluir posteriormente o agente que um link de demonstração usa, o link continuará funcionando: seus chats irão para o roteamento padrão da sua conta, e a lista mostrará “agente excluído, usa o padrão” ao lado dele. Excluir o agente que é o padrão do seu widget de chat não afeta os links fixados em outro agente.

Às vezes, não há um site para colocar o widget — você quer entregar um link a alguém e fazer com que conversem com seu assistente imediatamente. Todo widget de chat possui um:

  1. Abra o painel Gerenciar e role até Canais e Incorporação.
  2. Encontre Link de compartilhamento (fica logo abaixo do link de demonstração para cliente).
  3. Clique em Copiar para pegar o link, ou em Abrir para testar você mesmo.

Ao abri-lo, nada aparece além do seu assistente, preenchendo a tela inteira — sem site por trás, sem bolha para clicar primeiro, nada para instalar. Coloque-o na sua biografia do Instagram, em um código QR em um panfleto, em uma assinatura de e-mail ou em uma mensagem de WhatsApp para um cliente em potencial.

O link de compartilhamento segue o roteamento padrão do seu widget de chat. Para abrir um agente específico, adicione ?agent=AGENT_ID ao final do link; cada chat proveniente dele será então atribuído a esse agente e respondido por ele, enquanto a página mantém o nome e a mensagem de abertura do seu widget.

Algumas coisas que vale a pena saber:

  • Os chats do link são reais. Eles chegam à sua caixa de entrada, seu agente os responde e eles consomem créditos como qualquer outra conversa.
  • A página não contém nossa marca. Ela mostra apenas seu assistente e nada mais, e é mantida fora dos resultados de pesquisa.
  • Funciona no seu próprio endereço. Se o seu provedor executa o aplicativo no próprio domínio, o link também usa esse endereço, para que nada desconhecido apareça nele.
  • Um visitante por link, por navegador. Quem o abre mantém a mesma identidade naquele navegador, portanto, voltar mais tarde continua a mesma conversa em vez de iniciar a de um estranho. Um navegador diferente, ou o link de um widget diferente, é um visitante diferente.

Enviar páginas diferentes para agentes diferentes

Por padrão, todo chat que chega através do seu widget é tratado pelo mesmo agente. Você pode substituir isso por página, para que os visitantes na sua página de preços falem com seu agente de vendas, enquanto os visitantes na sua página de ajuda falem com seu agente de suporte, tudo a partir do mesmo widget de chat.

Existem duas maneiras de obter o código:

  • A partir do agente. Na página Agentes de IA, clique no botão </> na linha, ou abra o agente e vá para a aba Pontos de entrada. De qualquer forma, você obtém um snippet pronto para colar, já apontado para esse agente.

    A aba Pontos de entrada de um agente também possui um painel Widget de chat no site que mostra quantos chats de site esse agente já está gerenciando. Chats de um embed chegam ao agente diretamente, portanto, você não precisa criar uma regra de ponto de entrada para eles — um agente sem nenhuma regra ainda responde ao seu embed.

    O botão </> só aparece em agentes ativos. Um agente pausado receberia o chat, mas nunca responderia, portanto a opção fica oculta até que você a reative. Não há canal para configurar para um agente — um agente pode atender um chat de qualquer canal.

  • A partir das configurações do widget. Em Configurações → Canais → Gerenciar no seu widget de chat, defina Encaminhar estes chats para e copie o snippet abaixo. Alterar o menu suspenso reescreve o snippet.

O snippet flutuante carrega o destino no endereço:

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID?agent=AGENT_ID" defer></script>

O snippet em linha o carrega no <div>, para que uma página possa conter vários chats indo para lugares diferentes:

<div data-chat-widget="CONFIG_ID" data-agent="AGENT_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

Snippets copiados antes da desativação das campanhas contêm ?campaign= ou data-campaign= em vez disso. Eles continuam funcionando, então não há necessidade de colar novamente.

Algumas coisas que vale a pena saber:

  • Use o botão de copiar em vez de digitar o ID manualmente. Se o ID não corresponder a um agente na sua conta, o chat ainda funcionará, mas retornará ao seu roteamento padrão.
  • Alguém que já está no meio de uma conversa permanece com quem começou, mesmo que depois acesse uma página que aponte para outro lugar. Isso evita que uma conversa mude de personalidade no meio do caminho.
  • Um destino específico por página tem prioridade sobre o padrão da sua conta e sobre gatilhos de palavras-chave.

Informe ao Widget quem é o visitante (Avançado)

Se você colocar o widget de chat dentro de uma área de membros, um portal do cliente ou um aplicativo onde as pessoas já estão conectadas, seu site já sabe quem elas são. Você pode repassar essas informações ao widget para que o visitante não precise fornecer detalhes que já informou anteriormente, e para que sua IA possa usar o que você já sabe sobre ele.

Adicione um pequeno bloco de configurações antes do script do widget:

<script>
  window.chatWidgetSettings = {
    visitor: {
      id: "12345",
      name: "Maria",
      email: "maria@example.com",
      phone: "+391234567890"
    },
    data: {
      plan: "Professional",
      customer_since: "2024",
      last_order: "A-2291"
    }
  };
</script>
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

Sua página deve preencher esses valores no lado do servidor, a partir de quem estiver logado.

Para salvar também um sobrenome, adicione last_name ao lado de name no bloco visitor (data-visitor-last-name em um embed em linha). É opcional: um nome e um e-mail ainda são suficientes para pular o formulário, independentemente de Coletar sobrenome estar ativado ou não.

Duas coisas acontecem:

  • O formulário “Antes de começarmos…” é ignorado. Com um nome e um e-mail fornecidos, o visitante vai direto para a conversa, e esses detalhes são salvos no contato dele exatamente como se ele os tivesse digitado.
  • Tudo em data é repassado para sua IA. Qualquer coisa que você colocar lá — plano, número do pedido, data de renovação, saldo de crédito, quantos assentos eles possuem — torna-se parte do que a IA sabe sobre aquela pessoa, para que ela possa responder “quando meu plano renova?” sem pedir que eles expliquem quem são primeiro. Use os nomes de campo que fizerem sentido para você; eles aparecerão no contato em Campos Personalizados. Até 20 valores, enviados atualizados a cada mensagem, então, se o plano mudar no meio da conversa, a IA verá o novo.

Para incorporações em linha (inline), você pode colocar as mesmas informações no <div>, o que é útil quando uma página contém vários chats:

<div data-chat-widget="CONFIG_ID"
     data-visitor-name="Maria"
     data-visitor-email="maria@example.com"
     data-visitor-data='{"plan":"Professional"}'
     style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

Se o seu site só sabe quem é o visitante após o carregamento da página — um aplicativo de página única onde o login ocorre sem recarregar a página, por exemplo — chame isto sempre que tiver os detalhes, e o widget se atualizará:

<script>
  window.chatWidget.setVisitor({
    visitor: { id: "12345", name: "Maria", email: "maria@example.com" },
    data: { plan: "Professional" }
  });
</script>

Algumas coisas que vale a pena saber:

  • Se duas pessoas diferentes fizerem login no mesmo computador, a segunda iniciará uma nova conversa em vez de ver o chat da primeira. O widget percebe a mudança de pessoa e é reiniciado.
  • Por si só, isso serve para contexto, não para autenticar alguém. As conversas continuam sendo mantidas separadas como sempre foram, portanto, passar um id não permite que ninguém abra o chat de outra pessoa, e alguém usando um dispositivo ou navegador diferente iniciará uma nova conversa lá. Para manter a conversa entre dispositivos, assine o id conforme descrito a seguir.
  • É opcional. Um widget em uma página pública normal não precisa de nada disso e se comporta exatamente como antes.

Retome a mesma conversa em qualquer dispositivo (ID de visitante autenticado)

Se seus clientes possuem contas, você pode fazer com que o chat os acompanhe: faça login em um celular, continue em um laptop, e será a mesma conversa com o mesmo contato em sua caixa de entrada, e a IA ainda saberá tudo o que foi dito. Para isso, o Your AI Connector precisa de uma prova de que o visitante é realmente quem sua página diz que ele é; caso contrário, qualquer pessoa poderia digitar um número de cliente em seu navegador e ler o chat desse cliente. A prova é uma assinatura que você calcula em seu servidor.

  1. No painel Gerenciar do widget, em Canais e Incorporação (Channels & Embed), localize Visitantes autenticados (Signed-in visitors) e clique em Gerar segredo (Generate secret). Copie o segredo de identidade. Mantenha-o apenas no seu servidor; nunca o coloque na própria página.
  1. Quando seu servidor renderizar uma página para um cliente autenticado, calcule um HMAC-SHA256 do ID desse cliente usando o segredo, como uma string hexadecimal em minúsculas:
// Node.js
const hash = require("crypto").createHmac("sha256", IDENTITY_SECRET).update(customerId).digest("hex");
// PHP
$hash = hash_hmac('sha256', $customerId, IDENTITY_SECRET);
# Python
import hmac, hashlib
hash = hmac.new(IDENTITY_SECRET.encode(), customer_id.encode(), hashlib.sha256).hexdigest()
  1. Coloque o ID e o hash no bloco de configurações, ao lado do nome e e-mail que você já passa:
<script>
  window.chatWidgetSettings = {
    visitor: {
      id: "12345",
      hash: "3f2a…e91c",
      name: "Maria",
      email: "maria@example.com"
    }
  };
</script>
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>

A incorporação inline usa o mesmo valor que data-visitor-hash no <div>, e o window.chatWidget.setVisitor({ visitor: { id, hash } }) funciona para aplicativos que autenticam pessoas sem recarregar a página.

O que acontece quando a assinatura é verificada:

  • O chat do cliente é armazenado em sua conta em vez de no navegador, portanto, é a mesma conversa em todos os dispositivos e navegadores onde ele estiver autenticado, e um único contato em sua caixa de entrada.
  • Suas mensagens anteriores são carregadas no novo dispositivo, e a IA continua de onde parou.
  • Se a assinatura estiver incorreta, o widget se comporta silenciosamente como antes, como um chat normal por navegador, e imprime o motivo no console do navegador para que um desenvolvedor possa identificá-lo. Seus visitantes nunca verão um erro.
  • O ID é comparado exatamente como você o enviou, portanto, assine o mesmo valor que você passa como id e use o mesmo ID para a mesma pessoa em todos os lugares.

Duas coisas para saber:

  • Regenerar no painel Gerenciar fornece um novo segredo. As páginas que ainda assinam com o antigo retornam para chats normais por navegador até que seu servidor use o novo segredo. As conversas existentes são mantidas; elas estão vinculadas ao ID do cliente, não ao segredo.
  • Uma conversa que alguém teve antes de se autenticar, como um visitante anônimo, permanece como um chat separado. A conversa baseada na conta começa com a primeira mensagem enviada enquanto estiver autenticado.

Altere as configurações do widget a partir do seu próprio código (API)

Tudo no painel Gerenciar do widget também pode ser alterado por meio da API REST, o que é útil se você gerencia muitos sites ou deseja que o botão de anexo seja desativado automaticamente para um cliente. Envie uma PATCH para https://api.youraiconnector.com/v1/chat-widget-configs/CONFIG_ID com sua chave de API e apenas os campos que deseja alterar — por exemplo, {"show_upload_button": false} oculta o botão de anexo, {"show_emoji_button": false} oculta o seletor de emojis e {"launcher_icon": "chat-dots"} troca o ícone do iniciador. CONFIG_ID é o mesmo identificador usado no seu script de incorporação. A lista completa de campos aceitos (nome, mensagem de abertura, cores, ícone do iniciador, domínios permitidos, formulário de informações do visitante, aviso de privacidade, tema, estilo de canto e fonte) está na Referência da API em Widget de Chat. Os sites aplicam a alteração na próxima vez que a página for carregada.

O que esperar após a instalação

Depois de adicionar o script ao seu site, o widget de chat criará automaticamente um botão de chat no canto do seu site (canto inferior direito por padrão). O widget permanece em uma posição fixa conforme os usuários rolam suas páginas, garantindo que ele esteja sempre acessível.

Quando os visitantes clicam neste botão, ele se expande para uma janela de chat completa onde eles podem iniciar uma conversa, exibindo sua mensagem de abertura. Se a opção Coletar informações do visitante estiver ativada, um pequeno formulário aparece primeiro solicitando o nome e o e-mail (e, opcionalmente, o telefone) antes que eles possam digitar.

A interface do chat se adapta automaticamente a diferentes tamanhos de tela, funcionando perfeitamente tanto em computadores quanto em dispositivos móveis.

Testando sua implementação

Após adicionar o widget ao seu site, teste se ele funciona:

  1. Abra seu site em um navegador.
  2. Clique no botão de chat para abrir o widget.
  3. Envie uma mensagem de teste e confirme se você recebe uma resposta.
  4. Repita em um dispositivo ou navegador diferente para confirmar se funciona em todos os lugares.

Se o widget de chat não aparecer no seu site, verifique o seguinte:

  1. Certifique-se de ter substituído CONFIG_ID pelo seu identificador de configuração real.
  2. Certifique-se de que a tag de script esteja posicionada antes da tag de fechamento </body>.
  3. Verifique o código quanto a erros de digitação.
  4. No Shopify, certifique-se de ter editado o tema publicado e clicado em Salvar. Uma edição feita em um rascunho ou tema duplicado nunca chega à sua loja ativa.

Atrás de um Firewall Corporativo

Se o widget carrega para o público, mas não para a equipe na rede do escritório, a rede quase certamente está bloqueando o domínio de onde ele é carregado. Peça à sua equipe de TI para permitir, via HTTPS normal na porta 443:

  • O domínio no seu snippet de incorporação — o endereço na linha <script src="..."> que você copiou do painel Gerenciar.
  • api.youraiconnector.com — o widget também envia suas mensagens para cá.

Nada mais precisa ser aberto: sem portas extras e sem regras de entrada. Se o widget ainda não aparecer após isso, abra o console do desenvolvedor do seu navegador na página e nos envie o que ele relata — uma solicitação bloqueada nomeia o domínio que foi recusado, o que geralmente é a resposta completa.