Widget de Chat
Guia de Integração do Widget de Chat no Website
Adicione um widget de chat intuitivo ao seu website que permite aos visitantes comunicarem diretamente através da interface do seu site. O processo de integração é simples e fornecerá ao seu website capacidades de mensagens integradas.
Criar e configurar o widget de chat
Como chegar lá:
- Clique em Definições perto da parte inferior da barra lateral esquerda. (Num telemóvel, toque primeiro no ícone de menu ☰ no canto superior para abrir a barra lateral.)
- Na barra lateral esquerda de Definições, em Canais, clique em Canais.
- Encontre o cartão Widget de chat do site.
- Se ainda não tiver um widget, clique em Ligar para criar um com um nome de exibição e uma mensagem de boas-vindas.
- Depois de criado, clique em Gerir a qualquer momento para abrir o painel de configuração completo.
As alterações que guarda são aplicadas automaticamente ao seu widget ativo — não é necessário voltar a colar o código de instalação após efetuar uma alteração.
Uma Pré-visualização em direto encontra-se logo ao lado das definições: uma página web de exemplo com o seu widget real em execução, mostrando as suas cores, posição, logótipo, ícone de lançamento e janela proativa exatamente como os visitantes os verão. Segue as suas edições à medida que as faz, por isso não precisa de guardar para ver como fica uma alteração de cor ou tema. Pode até clicar no botão de chat dentro da pré-visualização para abrir o widget e experimentá-lo.
O que pode personalizar
O painel Gerir está organizado em quatro secções.
Aspeto
- Tema de estilo: Redesenhe todo o widget com um clique. Seis temas definem o aspeto, as cores, os cantos e o tipo de letra em conjunto: Classic (o aspeto sólido original — uma barra de cabeçalho colorida num painel plano), Glass (um painel translúcido e fosco que desfoca suavemente a página por trás, com o cabeçalho e a caixa de mensagens a flutuar como cartões arredondados no seu interior), 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 — depois de escolher um, pode continuar a alterar qualquer cor ou definição individualmente. Os novos widgets começam no Glass; a mudança é instantânea onde quer que o widget esteja incorporado, sem alterações de código no seu site.
- Cantos e Tipo de letra: Dois seletores 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 Tipo de letra escolhe o tipo de letra que os visitantes veem (Predefinido, Serif, Arredondado ou Mono) — os tipos de letra provêm do que já existe no dispositivo do visitante, pelo que não é carregado nada extra no seu site.
- Nome a apresentar: Mostrado no cabeçalho do widget.
- Logótipo: Carregue uma imagem que aparece no topo do chat. Utilize o logótipo da sua empresa ou uma fotografia 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 o seu logótipo carregado ou carregue uma imagem separada da sua autoria — útil se quiser uma fotografia de um membro real da equipa a cumprimentar os visitantes.
- Cores: Cinco cores, cada uma nomeando a parte do widget que 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 por cima. Balão do bot é o fundo das respostas do seu bot e do indicador de escrita, com Texto do balão do bot para as palavras dentro deles e os pontos de escrita animados. Janela de chat é o painel por trá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 ficam com a mesma cor e os visitantes não conseguem distinguir as respostas do seu bot das suas próprias. Um balão de bot cinzento 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 um desvio horizontal e vertical (em píxeis) se este se sobrepuser a algo na sua página.
- Perguntas iniciais: Sugestões de resposta rápida (chips clicáveis) apresentadas no chat para que os visitantes possam começar com um toque em vez de escrever — por exemplo, “Quais são os vossos preços?” ou “Oferecem suporte?” — até 10.
- Linha de rodapé: Uma pequena linha opcional do seu próprio texto por baixo da caixa de mensagens, por exemplo, “Desenvolvido pela Sua Agência”. Está desativada por predefinição e nada é mostrado por baixo da caixa de mensagens enquanto estiver desativada. Ative-a, escreva o seu texto (até 40 caracteres) e, se desejar, adicione uma ligação começando com
https://; os visitantes que clicarem no texto abrem essa página num novo separador. As agências utilizam-na para colocar o 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: Reproduzir um som quando chega uma nova mensagem no chat.
- Pedir permissão para notificações: Opcionalmente, solicitar aos visitantes que permitam notificações do navegador, para que sejam alertados sobre respostas mesmo quando mudam de separador.
- Balão de pop-up proativo: Um pequeno balão opcional que aparece ao lado do botão de chat para convidar as pessoas. Ative-o para definir a sua mensagem, o texto do botão aceitar/recusar e quantos segundos esperar antes de aparecer. O balão fecha-se automaticamente após 20 segundos se o visitante não clicar nele. É o único texto que o widget mostra ao lado do botão de chat: não existe uma definição para uma etiqueta permanente ao lado do botão.
- Velocidade de resposta da IA: Um seletor entre Mais lenta (mais humana — a IA demora um pouco antes de responder) e Velocidade máxima (mais robótica — as respostas surgem o mais rapidamente possível). Equilibrada situa-se no meio. A primeira mensagem de uma resposta chega com o atraso definido pelo seletor, com o indicador de escrita a aparecer pouco antes.
- Mostrar uma nota de ocupado enquanto a IA trabalha: Desativado por predefinição. Quando uma resposta demora mais do que alguns segundos, por exemplo, porque o seu agente está a procurar algo noutro sistema, os visitantes veem uma pequena linha ao lado dos pontos de escrita: “A preparar a sua resposta” após 5 segundos, “A procurar isso para si” após 15, depois “Ainda a tratar disso, quase pronto” e um pedido de desculpas pela espera se demorar mais tempo. As respostas rápidas mostram apenas os pontos. A linha segue o idioma do widget e só aparece enquanto a sua IA está realmente a trabalhar numa resposta, nunca quando a IA está desativada para esse chat ou uma pessoa assumiu o controlo.
Idiomas
O widget é multilingue por si só — não há nada para ativar.
-
Seleciona automaticamente o idioma do visitante. Primeiro, verifica o idioma que a sua página declara no HTML (
<html lang="it">) e, em seguida, recorre ao idioma do navegador do visitante. Se nenhum deles for um idioma que suportamos, as etiquetas do próprio widget são apresentadas no idioma em que escreveu a sua mensagem de boas-vindas, e a sua mensagem de boas-vindas, a bolha de pop-up e as perguntas iniciais aparecem exatamente como as escreveu. -
Um idioma de página que contradiga a sua saudação não é considerado fiá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 escreveu a sua mensagem de boas-vindas noutro, o widget trata o valor da página como uma predefinição do construtor: segue o idioma do navegador do visitante e, se esse não for um idioma que suportamos, utiliza o idioma em que escreveu. Uma página que altera o seu valorlangquando o visitante escolhe um idioma no seu site é sempre seguida. Se preferir não depender de nada disto, fixe o idioma na secção Comportamento. -
Ou escolha um você mesmo. O campo Idioma do widget na secção Comportamento está definido como Automático por predefinição, o que corresponde à deteção acima referida. Escolha um idioma aí e as etiquetas do próprio widget (os campos Nome próprio, E-mail e Telefone do formulário do visitante e o respetivo texto de exemplo, o aviso de privacidade, os botões) permanecem nesse idioma, independentemente do que a página ou o navegador indiquem. Utilize esta opção quando o seu construtor de sites não declarar o idioma correto ou quando pretender um idioma fixo para todos os visitantes.
-
Idiomas suportados: Inglês, Holandês, Alemão, Francês, Espanhol, Italiano, Português, Romeno, Polaco, Árabe, Finlandês, Filipino, Esloveno, Tailandês, Bangla, Japonês, Norueguês (Bokmål) e Turco. Esta é a lista para os botões e etiquetas do próprio widget.
-
Os idiomas escritos da direita para a esquerda são dispostos da direita para a esquerda. Para visitantes que utilizam Árabe, Hebraico, Persa e Urdu, toda a janela de chat é espelhada: o cabeçalho, as bolhas de mensagem, os pontos de digitação, o formulário do visitante e a caixa de mensagem começam todos a partir da direita. O botão da bolha permanece no canto que escolheu. Os visitantes que utilizam Hebraico, Persa e Urdu veem as etiquetas em Inglês (ou no idioma que fixou), mas o esquema continua a seguir o seu idioma. Uma mensagem escrita numa direção diferente, como uma resposta em Inglês num chat em Árabe, continua a ser lida na ordem correta.
-
As suas mensagens são traduzidas para si. Sempre que guarda, a sua mensagem de boas-vindas, a bolha de pop-up proativa e as perguntas iniciais são traduzidas para todos os dezoito idiomas acima referidos. Só precisa de as escrever uma vez, no idioma que preferir: o idioma em que escreveu é reconhecido a partir do próprio texto, essa versão é mantida palavra por palavra e todos os outros idiomas são uma tradução da mesma. Não importa qual é o idioma definido na sua conta.
-
Escreva a sua própria versão para um idioma. A secção Traduções do painel Gerir, logo abaixo de Comportamento, permite-lhe substituir 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, em seguida, preencha qualquer um dos seguintes campos: Mensagem de boas-vindas, Mensagem de pop-up, o Texto de aceitação e Texto de recusa do pop-up (apresentados enquanto a bolha de pop-up está ativa) e Perguntas iniciais. Cada campo mostra a tradução automática a cinzento; Começar a partir da tradução automática copia-a para que possa editar a partir daí. Tudo o que deixar em branco mantém a tradução automática. Os idiomas que escreveu pessoalmente são listados primeiro, marcados como O seu próprio texto, e Remover o meu texto em (idioma) reverte para a tradução automática desse idioma. O seu próprio texto é mantido quando edita posteriormente o texto original; apenas as traduções automáticas são refeitas.
-
Os botões de pop-up também são traduzidos. Os botões de Aceitar e Recusar da bolha de pop-up proativa são traduzidos juntamente com as suas outras mensagens, para que um visitante espanhol deixe de ver botões em Inglês.
-
Escreva cada mensagem apenas num idioma. Se colocar dois idiomas no mesmo campo — uma linha em Inglês e uma linha em Italiano, por exemplo — o conjunto é tratado como uma única mensagem e traduzido tal como está, pelo que um visitante italiano acaba por ver a mesma frase duas vezes. Escreva-a uma vez, no idioma que preferir.
-
A IA responde no idioma do visitante. Independentemente do idioma em que alguém escreve, o seu agente responde nesse mesmo idioma, independentemente do idioma em que as etiquetas do widget são apresentadas. Se preferir que responda sempre num idioma fixo, indique-o nas instruções do seu agente.
-
Defina o idioma por página no código de incorporação. Utiliza um widget num site em inglês e uma cópia traduzida do mesmo? Adicione
data-langà etiqueta de script do widget em cada página.data-lang="es"mostra o widget em espanhol nessa página, independentemente do que o navegador diga;data-lang="page"faz com que siga o valor<html lang="...">da própria página (por isso,lang="es-MX"resulta em espanhol), mesmo quando a sua mensagem de abertura está escrita noutro idioma. Esta opção prevalece sobre o campo Idioma do widget, que por sua vez prevalece sobre a deteçã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 Gerir tal como está e adicione apenas o atributo data-lang. Para um painel de chat incorporado, coloque data-lang no <div data-chat-widget="…">.
Dica: se o seu site não definir um atributo lang na sua etiqueta <html>, adicione um. É o sinal mais forte que temos para escolher o idioma correto, especialmente para visitantes que navegam a partir do estrangeiro.
Captura de leads e privacidade
- Recolher informações do visitante: Desativado por predefinição. Quando ativado, é pedido aos visitantes o seu nome e e-mail (e opcionalmente o telefone) antes de a conversa começar, para que capture o contacto mesmo que saiam a meio do chat.
- Título do formulário e Subtítulo do formulário: Personalize o cabeçalho e a breve explicação apresentados acima do formulário.
- Recolher número de telefone: Ative para pedir também um número de telefone; desativado recolhe apenas nome e e-mail.
- Recolher apelido: Desativado por predefinição. Ative para adicionar um campo obrigatório de Apelido logo após o Nome próprio. É guardado no contacto como o seu apelido, para que a sua IA e tudo o que esta consulta nos seus próprios sistemas tenha o nome completo desde a primeira mensagem. Os visitantes que já preencheram o formulário antes de ter ativado esta opção não serão questionados novamente.
- E-mails de resposta não lida para visitantes: um visitante que deixou um endereço de e-mail e não viu a sua resposta após 15 minutos recebe um e-mail a encaminhá-lo de volta para o chat. Desative em Definições → Notificações → Visitantes do widget de chat. Consulte 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 a conversa e escolha Continuar no WhatsApp no menu de três pontos (o WhatsApp Web ou o WhatsApp Business precisa de estar ligado). A Your AI Connector cria uma conversa de WhatsApp associada para a mesma pessoa, copia o nome, o e-mail e os detalhes, e a IA transfere o que foi dito no seu site, para que ninguém tenha de repetir o que já disse. O chat do site permanece onde está e ambas as conversas apontam uma para a outra em Conversas associadas no painel de contacto. Consulte Interface de Chat.
Um visitante deixou o seu e-mail e não efetuou a reserva — posso fazer um acompanhamento por e-mail? Sim, com uma automatização. Um passo Criar contacto com o Canal definido como E-mail transforma o endereço que o visitante deixou num contacto de e-mail no seu Canal de e-mail ligado, e um passo Enviar mensagem a seguir é enviado como um e-mail; as respostas chegam ao Chats para o seu agente de e-mail. A receita completa, incluindo como parar a sequência assim que eles disserem que efetuaram a reserva, encontra-se em Automatizações → Exemplo: acompanhamentos por e-mail para leads de chat no website.
O agente de IA pode oferecer a mudança para o WhatsApp por si próprio? Sim, e não precisa de nenhuma funcionalidade extra — basta uma linha nas instruções do agente. Crie uma Ligação Curta para o seu número de WhatsApp com uma mensagem predefinida, como “Olá, estava a falar no vosso site e quero continuar por aqui”, e depois indique ao agente quando a deve enviar, por exemplo: “Se o visitante precisar de sair, quiser continuar mais tarde ou pedir o WhatsApp, ofereça a continuação por lá e envie esta ligação: (a sua ligação curta)”. As ligações no widget podem ser clicadas, pelo que o visitante chega ao WhatsApp com o seu número selecionado e a mensagem pré-escrita, e a sua primeira mensagem abre uma conversa de WhatsApp na sua caixa de entrada. Se o visitante deixou o número de telefone a partir do qual escreve (com o código de país) no formulário do widget, a Your AI Connector associa as duas conversas automaticamente e a IA no WhatsApp já conhece o chat do site, exatamente como acontece com Continuar no WhatsApp. Se não foi recolhido nenhum número de telefone, as duas conversas não são associadas, por isso mantenha a mensagem predefinida suficientemente específica para que o agente do WhatsApp saiba de onde veio a pessoa.
- Exigir reconhecimento da política de privacidade: Opcionalmente, exija que os visitantes aceitem a sua política de privacidade antes de iniciarem o chat e defina o URL para o qual esta aponta.
O que é que o widget armazena no navegador de um visitante e preciso de o colocar atrás de um aviso de cookies? Nada é armazenado apenas por carregar uma página. O widget não escreve cookies nem utiliza armazenamento do navegador até que o visitante decida conversar: enviar uma primeira mensagem, preencher o formulário de informações do visitante ou aceitar a sua política de privacidade. A partir desse momento, mantém um ID de conversação aleatório e uma cópia da conversação nesse navegador, como armazenamento próprio (first-party) no seu domínio, para que o chat ainda lá esteja quando o visitante regressar. Não carrega scripts de análise ou rastreio e não define cookies de terceiros. Como nada é escrito até que o visitante peça para conversar, enquadra-se no armazenamento estritamente necessário para um serviço solicitado pelo visitante, pelo que pode carregá-lo sem o restringir atrás de um aviso de consentimento. Se o seu site utilizar uma ferramenta de consentimento de qualquer forma, não há problema em manter o widget atrás da mesma; o chat simplesmente aparece assim que o visitante aceitar.
Canais e incorporação
- Botão de anexo: Permite que os visitantes enviem imagens e ficheiros no chat.
- Seletor de emojis: Adiciona um seletor de emojis junto à caixa de mensagem.
- Ligações para canais: Opcionalmente, inclua ligações para WhatsApp, Instagram ou Messenger para que os visitantes possam continuar a conversa na plataforma que preferirem. Isto só aparece depois de ligar um número de WhatsApp (WhatsApp Business ou WhatsApp Web), Instagram ou Messenger. Ativar a ligação do WhatsApp preenche o seu número ligado; a ligação permanece editável, pelo que, após alterar os números, pode escrever o novo no local.
- Botões de ação: Uma linha de atalhos no topo do chat que levam o visitante para outro local em vez de para uma conversa — veja Botões de ação abaixo.
- Lista branca de domínios: Restrinja os websites que podem incorporar o seu widget. Adicione os domínios onde o instalou (por exemplo,
example.comou*.example.com); deixe vazio para permitir qualquer domínio. - Países bloqueados: Mantenha o widget longe de visitantes em países que não serve. Os visitantes cuja localização de rede seja num país que escolher nunca verão o widget, e qualquer chat que tentem iniciar será recusado. Deixe vazio para permitir a todos. Veja Manter bots e consumo de créditos fora abaixo.
- Encaminhar estes chats para: Escolha o agente que deve tratar dos chats provenientes do código que está prestes a copiar. Deixe em Predefinição da conta para utilizar o encaminhamento 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).
- Ligação de demonstração para cliente: Cole qualquer endereço de website e clique em Criar ligação para obter uma ligação partilhável que abre esse site com o seu widget em execução sobreposto, sem necessidade de instalar nada do lado deles. Cada ligação que criar é listada e pode desativar cada uma delas. Veja Mostrar o widget no website de outra pessoa abaixo.
- Partilhar ligação: Uma ligação pronta a usar que abre o seu assistente numa página própria, em ecrã inteiro, sem necessidade de um website. Copie-a e envie-a para qualquer lugar. Veja Partilhar uma ligação direta para o chat abaixo.
Na parte inferior do painel, uma ação Eliminar widget de chat remove o widget do seu site imediatamente — isto não pode ser anulado e os visitantes deixarão de ver o balão de chat.
Botões de ação
Alguns visitantes não querem conversar. Querem o seu número de telefone, a sua morada ou o seu e-mail, e querem-no com um toque. Os botões de ação são uma linha de atalhos no topo do painel de chat exatamente para isso.
Adicione até seis. Cada um tem uma etiqueta (as palavras no botão) e um destino, e o destino depende da ação que escolher:
| Ação | O que o visitante recebe | O que deve preencher |
|---|---|---|
| Ligar | O marcador de telefone abre-se com o seu número pronto | O seu número de telefone, p. ex. +1 555 123 4567 |
| Enviar SMS | A aplicação de mensagens abre uma nova mensagem para si | O seu número de telefone |
| O WhatsApp abre uma conversa consigo | O seu número de WhatsApp, ou uma ligação wa.me que já possua |
|
| A aplicação de correio eletrónico abre um novo e-mail para si | O seu endereço de e-mail | |
| Direções | O Google Maps abre-se com a sua localização | A sua morada, ou uma ligação de mapas que já possua |
| Ligação | A página abre-se num novo separador | Qualquer endereço web completo que comece por https:// |
Estes botões não utilizam créditos. Tocar num botão não envia uma mensagem nem inicia uma conversa — apenas leva o visitante para onde ele pediu para ir. Apenas uma conversa real com o seu agente de IA utiliza 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 assim tocar em Direções depois, sem recarregar a página.
- As suas etiquetas são apresentadas exatamente como as escreveu. Ao contrário da sua mensagem de abertura e das perguntas iniciais, as etiquetas dos botões não são traduzidas automaticamente, por isso, se atende visitantes em vários idiomas, mantenha as etiquetas curtas e óbvias (ou escreva-as no seu idioma principal).
- Preencha um botão corretamente ou não será guardado. Se um número de telefone, endereço de e-mail ou ligação não for válido, o painel indica-o e bloqueia o botão Guardar alterações em vez de publicar um botão que não faria nada no seu site.
- Não são respostas de FAQ. Os botões de ação apenas enviam as pessoas para outro local; não respondem com texto pré-definido. As perguntas são da responsabilidade do seu agente de IA, que as responde a partir da sua base de conhecimentos. Se quiser sugerir o que perguntar, utilize as perguntas iniciais em Aparência.
O que não pode personalizar
O painel Gerir é o conjunto completo de opções. Em particular:
- Sem CSS ou folha de estilos personalizada. O estilo é definido pelo que o tema, os seletores de canto, tipo de letra e cor oferecem — não pode injetar o seu próprio CSS no widget, e as regras na sua página não chegarão ao seu interior.
- Sem texto de marcador de posição personalizado na caixa de mensagem.
- Sem incorporação de vídeo dentro do chat.
Se um destes pontos for um impedimento para si, a incorporação em linha oferece-lhe o maior controlo: o widget fica num contentor na sua própria página, que dimensiona e posiciona como desejar.
Manter Bots e Consumo de Créditos Fora
Cada resposta de IA custa créditos, por isso um script (ou uma pessoa aborrecida) a abrir chat após chat no seu site é a única coisa contra a qual um widget público tem de se defender. O widget trata da maior parte disso sozinho, e duas definições no painel Gerir permitem-lhe reforçar a segurança para o seu site.
- Lista de permissões de domínio. Apenas os websites que listar podem apresentar o widget. Qualquer pessoa que copie o seu código de incorporação para outro site não obterá nada.
- Países bloqueados. Os visitantes cuja localização de rede seja num país que bloqueou nunca verão o widget, e qualquer conversa que tentem iniciar será recusada. A localização provém da ligação do visitante: alguém que utilize uma VPN aparecerá como sendo do país da VPN, e um visitante cuja localização não possa ser determinada terá acesso em vez de ser bloqueado. A sua própria pré-visualização dentro da aplicação continuará a funcionar, mesmo que bloqueie o país onde se encontra.
- Novas conversas por ligação. Uma ligação (na prática, um endereço de casa ou escritório) pode abrir 20 novas conversas por dia num widget. Os visitantes recorrentes que continuam a sua conversa existente não contam, apenas as conversas totalmente novas contam, pelo que um script que continue a iniciar conversas novas para obter respostas de IA esgota-se após 20, enquanto os visitantes reais nunca notam. Se muitas pessoas partilharem uma ligação no seu site (um campus, um centro de atendimento), aumente o número através da REST API com
max_new_chats_per_ip_daily;0desativa a verificação. - Verificação humana (opcional). Os visitantes passam por uma verificação rápida do Cloudflare Turnstile antes de a sua primeira mensagem ser enviada, pelo que um script não consegue iniciar conversas. A maioria das pessoas nunca clica em nada; o Cloudflare apenas apresenta uma caixa de verificação quando não tem a certeza. Utiliza as suas próprias chaves gratuitas do Turnstile, veja Adicionar uma verificação humana abaixo.
- Limites integrados. Além disso, cada sessão de navegador tem um limite de quantas mensagens pode enviar por minuto e por dia, e o agente que responde à conversa para de responder a um visitante assim que este atinge o Máximo de mensagens de IA por conversa definido em Limites de resposta.
Nada disto identifica dispositivos ou pessoas: o widget não armazena nada no navegador do visitante até que este escolha conversar (veja acima), e não existe recolha de impressões digitais (fingerprinting).
Adicionar uma verificação humana (Cloudflare Turnstile)
Ative esta opção quando os bots continuarem a abrir conversas no seu website e as definições acima não forem suficientes. A verificação é executada uma vez, logo antes de a primeira mensagem de um visitante ser enviada. Um visitante que passe na verificação pode continuar a conversar durante 24 horas sem a ver novamente, e qualquer pessoa que regresse a uma conversa anterior ainda pode lê-la antes da verificação.
- Inicie sessão na sua conta Cloudflare (uma conta gratuita é suficiente) e abra o Turnstile.
- Clique em Adicionar widget, dê-lhe um nome e adicione todos os domínios em que o seu widget de chat é executado (por exemplo,
yourshop.com). Deixe o modo de widget em Gerido. - Copie a Chave do site e a Chave secreta que o Cloudflare lhe apresenta.
- Na aplicação, abra o painel Gerir do seu widget de chat, ative a Verificação humana antes de conversar, cole ambas as chaves e guarde.
O que esperar:
- A verificação permanece desativada até que ambas as chaves sejam preenchidas, pelo que ativá-la sem chaves nunca bloqueia o acesso aos visitantes.
- Se um visitante falhar a verificação ou a deixar por resolver, a sua mensagem não é enviada e recebe um botão Tentar novamente.
- A verificação só aparece nos domínios que adicionou no Cloudflare. Em qualquer outro domínio, o Cloudflare recusa-a e ninguém nesse site pode enviar uma mensagem, por isso adicione todos os domínios antes de a ativar.
- Se o seu website utilizar uma Política de Segurança de Conteúdo (Content Security Policy), permita
https://challenges.cloudflare.compara scripts e frames, caso contrário a verificação não poderá ser carregada. - As chaves pertencem à 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.
- Abra o ficheiro HTML do seu website num editor de texto.
- Encontre a etiqueta de fecho
</body>— esta encontra-se normalmente no final do ficheiro. - Cole esta linha de código imediatamente antes da etiqueta
</body>, para que o resto da sua página seja carregado primeiro:
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>
- Substitua
CONFIG_IDpelo seu identificador de configuração único, apresentado na secção Canais e Incorporação do painel de Gestão. Este identificador é específico da sua conta e liga o widget ao seu sistema de mensagens.
O snippet não tornará o seu site mais lento: é um carregador minúsculo e o próprio widget é transferido em segundo plano sem bloquear a página. Se ainda assim pretender que o widget aguarde até que a sua página termine completamente de carregar, pode envolver o mesmo 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 pretende atrasar é a pequena bolha de convite em vez do carregamento do widget, essa opção é o atraso da Bolha de pop-up proativa na secção Comportamento acima — não é necessário código.
Instalação no Shopify
- No seu painel de administração do Shopify, vá a Loja online > Temas.
- No tema marcado como o 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.
- Abra layout/theme.liquid e desça até à tag de fecho
</body>perto do fim. - Cole a sua linha de instalação logo acima de
</body>e clique em Guardar:
<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID" defer></script>
Se instalou o widget antes de a linha de instalação incluir defer, o editor de código do Shopify mostra um sublinhado vermelho por baixo da mesma. 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 é guardado na mesma e o widget continua a funcionar. Adicionar defer conforme mostrado acima faz com que o sublinhado desapareça e não altera em nada o comportamento do widget, pelo que não há necessidade de reinstalar noutros sites.
Aqui tem um exemplo completo de como o seu ficheiro HTML deve parecer 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 numa Página (Avançado)
Se preferir que o chat apareça como parte da sua página — por exemplo, dentro de uma secção dedicada “Contacte-nos”, um separador de ajuda ou uma barra lateral — em vez de como uma bolha flutuante no canto, altere Snippet de incorporação para Em linha no painel de Gestão e copie o snippet em linha.
Tem este aspeto:
<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 no seu interior e preenche as suas dimensões. Aplique o estilo que desejar à div (atribua-lhe uma altura fixa, coloque-a dentro de um contentor flex, coloque-a numa célula de grelha, etc.) e o painel de chat adaptar-se-á.
Apenas precisa de uma etiqueta <script> na página, mesmo que esteja a incorporar vários widgets de chat. O script analisa a página à procura de cada <div data-chat-widget="…"> e monta um painel de chat em cada um.
Quando escolher entre inline ou flutuante:
- A bolha flutuante é a opção certa para um botão “Precisa de ajuda?” sempre disponível em todo o site.
- A incorporação inline é a opção certa quando o chat deve residir num local específico — uma página de suporte, uma barra lateral de base de conhecimento, um separador de ajuda na aplicação — e parecer uma parte nativa dessa página.
A incorporação em linha reutiliza a mesma configuração da bolha flutuante (logótipo, mensagem de abertura, captura de leads, perguntas iniciais, etc.), pelo que não precisa de configurar nada duas vezes.
Mostrar o Widget no Website de Outra Pessoa
Pode mostrar o seu widget de chat a funcionar num website que não controla — sem necessidade de código ou de acesso ao site deles. É a forma mais rápida de mostrar a um potencial cliente como o assistente ficaria nas suas próprias páginas.
- Abra o painel Gerir e desloque-se até Canais e Incorporação.
- Em Ligação de demonstração do cliente, escreva o endereço do website (por exemplo
www.theircompany.com). - Opcional: abaixo do campo, escolha o Agente que deve responder nesta demonstração, por exemplo, um agente que criou a partir do próprio website do potencial cliente para que fale sobre os seus serviços, preços e perguntas frequentes. Deixe em Predefinição da conta para utilizar o encaminhamento normal do seu widget de chat.
- Clique em Criar ligação. A ligação é copiada para si e aparece na lista abaixo do campo, com os botões Copiar e Abrir e o agente que utiliza.
- Envie a ligação para quem desejar mostrá-la.
Ao abrir a ligação, o website é carregado com o seu widget de chat a flutuar por cima, exatamente como apareceria se estivesse instalado. Qualquer pessoa com a ligação pode abri-la — não há nada em que iniciar sessão.
Algumas coisas que vale a pena saber:
- Os chats da demonstração são reais. As mensagens que um visitante envia numa demonstração chegam à sua caixa de entrada e são respondidas pelo seu agente, utilizando créditos como qualquer outra conversa.
- A página não tem marca. Mostra o site deles e o seu widget, e nada mais.
- Alguns sites não podem ser enquadrados. Vários sites (bancos, grandes retalhistas, qualquer coisa protegida por definições de segurança rigorosas) impedem que outras páginas os apresentem. Quando isso acontece, a ligação continua a funcionar: mostra uma janela de navegador simulada neutra em vez do site real, com o seu widget ativo por cima, para que a demonstração continue a cumprir o seu propósito.
- Não altera o site deles. Nada é instalado e nada é modificado — a demonstração existe apenas dentro dessa ligação.
- Desative uma ligação quando a demonstração terminar. Clique em Desativar junto à ligação na lista e confirme. A partir desse momento, qualquer pessoa que a abra verá uma página a indicar que a ligação foi desativada. O seu widget e as suas outras ligações de demonstração continuam a funcionar. Uma ligação que seja desativada não pode ser reativada; crie uma nova em vez disso.
- Ligações copiadas antes de 25 de setembro de 2026. As ligações de demonstração criadas antes da existência da lista não estão nela. Continuam a funcionar até clicar em Desativar essas abaixo da lista, o que as desativa todas de uma vez (e Reativá-las reverte a ação).
Uma ligação de demonstração criada sem um agente utiliza o encaminhamento predefinido da sua conta, independentemente da definição de Encaminhar estes chats para. Com um agente selecionado, cada chat dessa ligação é atribuído a esse agente e respondido por ele. O widget mantém o seu próprio aspeto, nome e mensagem de abertura. A ligação transporta-o como &agent=AGENT_ID; adicionar isso manualmente a uma ligação mais antiga também funciona (utilize &, não ?, porque a ligação já contém um ?).
Se eliminar posteriormente o agente que uma ligação de demonstração utiliza, a ligação continua a funcionar: os seus chats passam a ir para o encaminhamento predefinido da sua conta e a lista mostra “agente eliminado, utiliza a predefinição” ao lado. Eliminar o agente que é a predefinição do seu widget de chat não afeta as ligações associadas a outro agente.
Partilhar uma Ligação Direta para o Chat
Por vezes não existe um website onde colocar o widget — pretende dar a alguém uma ligação e fazer com que falem imediatamente com o seu assistente. Cada widget de chat tem uma:
- Abra o painel Gerir e desloque-se até Canais e Incorporação.
- Encontre Ligação de partilha (encontra-se logo abaixo da ligação de demonstração para cliente).
- Clique em Copiar para obter a ligação, ou em Abrir para a experimentar.
Ao abri-la, não aparece nada além do seu assistente, ocupando todo o ecrã — sem website por trás, sem bolha para clicar primeiro, nada para instalar. Coloque-a na sua biografia do Instagram, num código QR num folheto, numa assinatura de e-mail ou numa mensagem de WhatsApp para um potencial cliente.
A ligação de partilha segue o encaminhamento predefinido do seu widget de chat. Para abrir um agente específico, adicione ?agent=AGENT_ID ao final da ligação; cada chat proveniente da mesma é 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 da ligação são reais. Chegam à sua caixa de entrada, o seu agente responde-lhes e utilizam créditos como qualquer outra conversa.
- A página não contém a nossa marca. Mostra apenas o seu assistente e nada mais, sendo mantida fora dos resultados de pesquisa.
- Funciona no seu próprio endereço. Se o seu fornecedor executar a aplicação no seu próprio domínio, a ligação utiliza esse endereço também, pelo que não aparece nada de desconhecido.
- Um visitante por ligação, por navegador. Quem a abrir mantém a mesma identidade nesse navegador, pelo que voltar mais tarde continua a mesma conversa em vez de iniciar a de um estranho. Um navegador diferente, ou a ligação de um widget diferente, é um visitante diferente.
Enviar páginas diferentes para agentes diferentes
Por predefinição, todos os chats que chegam através do seu widget são tratados pelo mesmo agente. Pode substituir essa definição por página, para que os visitantes na sua página de preços falem com o seu agente de vendas, enquanto os visitantes na sua página de ajuda falam com o seu agente de suporte, tudo a partir do mesmo widget de chat.
Existem duas formas 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á ao separador Pontos de entrada. De qualquer forma, obterá um snippet pronto a colar que já aponta para esse agente.
O separador Pontos de entrada de um agente também possui um painel Widget de chat no website que mostra quantos chats de website esse agente já está a processar. Os chats provenientes de uma incorporação chegam diretamente ao agente, pelo que não precisa de criar uma regra de ponto de entrada para os mesmos — um agente sem quaisquer regras continua a responder à sua incorporação.
O botão </> só aparece em agentes ativos. Um agente em pausa receberia o chat, mas nunca responderia, pelo que a opção fica oculta até que a volte a ativar. Não existe nenhum canal a configurar para um agente — um agente pode atender um chat de qualquer canal.
-
A partir das definições do widget. Em Definições → Canais → Gerir no seu widget de chat, defina Encaminhar estes chats para e copie o snippet abaixo. Alterar a lista pendente reescreve o snippet.
O snippet flutuante transporta 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 transporta-o no <div>, pelo que uma página pode conter vários chats que vão para locais 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>
Os snippets copiados antes da desativação das campanhas contêm ?campaign= ou data-campaign= em vez disso. Continuam a funcionar, pelo que não há necessidade de voltar a colar.
Algumas coisas que vale a pena saber:
- Utilize o botão de copiar em vez de escrever o ID manualmente. Se o ID não corresponder a um agente na sua conta, o chat continua a funcionar, mas recorre ao seu encaminhamento predefinido.
- Alguém que já esteja a meio de uma conversa permanece com quem a iniciou, mesmo que mais tarde chegue a uma página que aponte para outro local. Isto evita que uma conversa mude de personalidade a meio.
- Um destino específico por página tem prioridade sobre a predefinição da sua conta e sobre os gatilhos de palavras-chave.
Diga ao Widget quem é o Visitante (Avançado)
Se colocar o widget de chat dentro de uma área de membros, um portal de cliente ou uma aplicação onde as pessoas já iniciaram sessão, o seu site já sabe quem elas são. Pode transmitir essa informação ao widget para que não seja pedido ao visitante detalhes que já lhe forneceu anteriormente, e para que a sua IA possa utilizar o que já sabe sobre ele.
Adicione um pequeno bloco de definiçõ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>
A sua página deve preencher esses valores no lado do servidor, a partir de quem estiver com sessão iniciada.
Para guardar também um apelido, adicione last_name junto a name no bloco visitor (data-visitor-last-name num embed em linha). É opcional: um nome e um e-mail continuam a ser suficientes para ignorar o formulário, independentemente de a opção Recolher apelido estar ativada ou não.
Acontecem duas coisas:
- O formulário “Antes de começarmos…” é ignorado. Com um nome e um e-mail fornecidos, o visitante entra diretamente na conversa e esses detalhes são guardados no seu contacto exatamente como se os tivesse escrito.
- Tudo o que está sob
dataé transmitido à sua IA. Qualquer coisa que coloque aí — plano, número de encomenda, data de renovação, saldo de crédito, quantos lugares têm — torna-se parte do que a IA sabe sobre essa pessoa, para que possa responder a “quando é que o meu plano renova?” sem pedir primeiro que expliquem quem são. Utilize os nomes de campo que fizerem sentido para si; estes aparecem no contacto em Campos Personalizados. Até 20 valores, enviados de novo com cada mensagem, por isso, se o plano mudar a meio da conversa, a IA vê o novo.
Para incorporações inline, pode colocar a mesma informação 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ó souber quem é o visitante após a página ter sido carregada — uma aplicação de página única onde o início de sessão ocorre sem recarregar a página, por exemplo — chame isto sempre que tiver os detalhes, e o widget atualizar-se-á:
<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 iniciarem sessão no mesmo computador, a segunda inicia uma nova conversa em vez de ver o chat da primeira. O widget deteta a mudança de pessoa e reinicia-se.
- Por si só, isto serve para contexto, não para autenticar alguém. As conversas continuam a ser mantidas separadas como sempre foram, por isso, passar um
idnão permite que ninguém abra o chat de outra pessoa, e alguém que utilize um dispositivo ou navegador diferente inicia uma nova conversa aí. Para manter a conversa entre dispositivos, autentique oidconforme descrito a seguir. - É opcional. Um widget numa página pública normal não precisa de nada disto e comporta-se exatamente como antes.
Retomar a mesma conversa em qualquer dispositivo (ID de visitante autenticado)
Se os seus clientes tiverem contas, pode fazer com que o chat os acompanhe: iniciam sessão num telemóvel, continuam num portátil, e é a mesma conversa com o mesmo contacto na sua caixa de entrada, e a IA continua a saber tudo o que foi dito. Para isso, o Your AI Connector precisa de prova de que o visitante é realmente quem a sua página diz que é; caso contrário, qualquer pessoa poderia introduzir um número de cliente no seu navegador e ler o chat desse cliente. A prova é uma assinatura que calcula no seu servidor.
- No painel Gerir do widget, em Canais e Incorporação, encontre Visitantes com sessão iniciada e clique em Gerar segredo. Copie o segredo de identidade. Mantenha-o apenas no seu servidor; nunca o coloque na própria página.
- Quando o seu servidor processar uma página para um cliente com sessão iniciada, calcule um HMAC-SHA256 do ID desse cliente utilizando o segredo, como uma cadeia 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()
- Coloque o ID e o hash no bloco de definições, a seguir ao nome e e-mail que já transmite:
<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 em linha assume o mesmo valor que o data-visitor-hash no <div>, e o window.chatWidget.setVisitor({ visitor: { id, hash } }) funciona para aplicações que autenticam utilizadores sem recarregar a página.
O que acontece quando a assinatura é validada:
- O chat do cliente é armazenado na sua conta em vez de no navegador, pelo que é a mesma conversa em todos os dispositivos e navegadores onde tenham sessão iniciada, e um único contacto na sua caixa de entrada.
- As suas mensagens anteriores são carregadas no novo dispositivo e a IA continua a partir de onde pararam.
- Se a assinatura estiver incorreta, o widget comporta-se silenciosamente como antes, como um chat normal por navegador, e imprime o motivo na consola do navegador para que um programador o possa identificar. Os seus visitantes nunca veem um erro.
- O ID é comparado exatamente como o enviou, por isso assine o mesmo valor que transmite como
ide utilize o mesmo ID para a mesma pessoa em todo o lado.
Duas coisas a saber:
- Regenerar no painel Gerir fornece-lhe um novo segredo. As páginas que continuam a assinar com o antigo revertem para chats normais por navegador até que o seu servidor utilize o novo segredo. As conversas existentes são mantidas; estão ligadas ao ID do cliente, não ao segredo.
- Uma conversa que alguém teve antes de iniciar sessão, como visitante anónimo, permanece um chat separado. A conversa baseada na conta começa com a primeira mensagem que enviam enquanto estão autenticados.
Alterar as definições do widget a partir do seu próprio código (API)
Tudo o que se encontra no painel Gerir do widget também pode ser alterado através da REST API, o que é útil se gerir muitos websites ou se pretender desativar automaticamente o botão de anexo para um cliente. Envie um PATCH para https://api.youraiconnector.com/v1/chat-widget-configs/CONFIG_ID com a sua chave de API e apenas os campos que pretende 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 lançador. CONFIG_ID é o mesmo identificador que consta no seu script de integração. A lista completa de campos aceites (nome, mensagem de abertura, cores, ícone do lançador, domínios permitidos, formulário de informações do visitante, aviso de privacidade, tema, canto e estilo de letra) encontra-se na Referência da API em Chat Widget. Os websites aplicam a alteração na próxima vez que a página for carregada.
O que esperar após a instalação
Assim que adicionar o script ao seu website, o widget de chat criará automaticamente um botão de chat no canto do seu website (por predefinição, no canto inferior direito). O widget permanece numa posição fixa à medida que os utilizadores percorrem as suas páginas, garantindo que está sempre acessível.
Quando os visitantes clicam neste botão, ele expande-se para uma janela de chat completa onde podem iniciar uma conversa, apresentando a sua mensagem de abertura. Se a opção Recolher informações do visitante estiver ativada, aparece primeiro um pequeno formulário a pedir o nome e o e-mail (e opcionalmente o telefone) antes de poderem escrever.
A interface de chat adapta-se automaticamente a diferentes tamanhos de ecrã, pelo que funciona perfeitamente tanto em computadores como em dispositivos móveis.
Testar a sua implementação
Após adicionar o widget ao seu site, teste se funciona:
- Abra o seu website num navegador.
- Clique no botão de chat para abrir o widget.
- Envie uma mensagem de teste e confirme se recebe uma resposta.
- Repita noutro dispositivo ou navegador para confirmar que funciona em todo o lado.
Se o widget de chat não aparecer no seu site, verifique o seguinte:
- Certifique-se de que substituiu
CONFIG_IDpelo seu identificador de configuração real. - Certifique-se de que a tag de script é colocada antes da tag de fecho
</body>. - Verifique o código quanto a erros de digitação.
- No Shopify, certifique-se de que editou o tema publicado e clicou em Guardar. Uma edição feita num rascunho ou num tema duplicado nunca chega à sua loja ativa.
Atrás de uma Firewall Corporativa
Se o widget carrega para o público, mas não para os funcionários na rede do escritório, a rede está quase certamente a bloquear o domínio a partir do qual ele é carregado. Peça à sua equipa de TI para permitir, através de HTTPS normal na porta 443:
- O domínio no seu snippet de incorporação — o endereço na linha
<script src="...">que copiou do painel Gerir. api.youraiconnector.com— o widget também envia as suas mensagens para aqui.
Não é necessário abrir mais nada: sem portas adicionais e sem regras de entrada. Se o widget continuar a não aparecer após isso, abra a consola de programador do seu navegador na página e envie-nos o que ela reporta — um pedido bloqueado indica o domínio que foi recusado, o que é, normalmente, a resposta completa.