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á:

1. 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.)
2. Na barra lateral esquerda de Definições, em Canais, clique em Canais.
3. Encontre o cartão Widget de chat do site.
4. 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.
5. 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 em conjunto o aspeto, as cores, os cantos e o tipo de letra: 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 afiados). 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, as bolhas e os botões (Redondo, Suave ou Afiado), 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, por isso não é carregado nada extra no seu site.
• Nome de exibição: Apresentado 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 de lançamento: 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 — ú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 se encontra por cima. Bolha do bot é o fundo das respostas do seu bot e do indicador de escrita, com Texto da bolha do bot para as palavras no seu interior e os pontos de escrita animados. Janela de chat é o painel por trás de todas as mensagens. Escolha uma cor para a Bolha do bot que seja claramente diferente da sua Cor da 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. Uma bolha 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 deslocamento horizontal e vertical (em píxeis) caso se sobreponha 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 apoio?” — até 10.

Comportamento #

• Mensagem de abertura: A primeira mensagem que os visitantes veem quando abrem 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 dos botões de aceitar/recusar e quantos segundos esperar antes de aparecer. O balão oculta-se automaticamente após 20 segundos se ninguém clicar nele (esse número é fixo) e, assim que um visitante clica em Não agora, ele permanece oculto durante o resto da visita. A janela de chat nunca se abre sozinha: abre-se quando o visitante clica no botão de chat ou no balão e permanece aberta até que a fechem.
• 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). O modo Equilibrado situa-se no meio.

Idiomas #

O widget é multilingue por si só — não há nada para ativar.

• Deteta automaticamente o idioma do visitante. Primeiro, verifica o idioma que a sua página declara no seu HTML (<html lang="it">), depois recorre ao idioma do navegador do visitante. Se nenhum for um idioma que suportamos, apresenta o inglês.
• Ou escolha um você mesmo. O campo Idioma do widget na secção Comportamento está definido como Automático por predefinição, que é a 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 seu texto de exemplo, o aviso de privacidade, os botões) permanecem nesse idioma, independentemente do que a página ou o navegador indiquem. Utilize isto quando o construtor do seu site não declara o idioma correto ou quando pretende 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 e filipino. Esta é a lista para os botões e etiquetas do próprio widget.
• As suas mensagens são traduzidas para si. Sempre que guarda, a sua mensagem de abertura, o balão de pop-up proativo e as perguntas iniciais são traduzidos para todos os doze idiomas acima. Só precisa de os escrever uma vez, no idioma que preferir.
• 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 — tudo será tratado como uma única mensagem e traduzido tal como está, pelo que um visitante italiano acabará 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 estão a ser apresentadas. Se preferir que responda sempre num idioma fixo, indique-o nas instruções do seu agente.

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 número de telefone) antes de a conversa começar, para que possa captar o contacto mesmo que estes saiam a meio da conversa.
• 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 o nome e o e-mail.

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.

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 de 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, Instagram ou Messenger.
• 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 quais os websites autorizados a incorporar o seu widget. Adicione os domínios onde o instalou (por exemplo, example.com ou *.example.com); deixe vazio para permitir qualquer domínio.
• Encaminhar estes chats para: Escolha a campanha ou 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 campanhas 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 para obter uma ligação partilhável que abre esse site com o seu widget em cima — sem necessidade de instalar nada do lado deles. Veja Mostrar o widget no website de outra pessoa 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:

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 personalizado ou folha de estilos. O estilo é o que os seletores de tema, 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 restrição geográfica ou de país. A Lista branca de domínios limita quais os websites que podem incorporar o widget; não existe forma de o mostrar ou ocultar com base na localização do visitante. Se precisar disso, oculte o snippet de incorporação manualmente nas páginas ou para os públicos-alvo onde não o pretende.
• Sem incorporação de vídeo dentro do chat.
• Sem temporizador de ocultação automática. O balão de convite desaparece sozinho após 20 segundos e esse número não pode ser alterado; a janela de chat aberta nunca se fecha sozinha. Se o balão estiver sobre o conteúdo da sua página, mova o widget com as compensações de Posição ou desative o balão e mantenha apenas o botão de lançamento.

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.

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 ficheiro HTML do seu website num editor de texto.
2. Encontre a etiqueta de fecho </body> — esta encontra-se normalmente no final do ficheiro.
3. 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"></script>

4. Substitua CONFIG_ID pelo 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.

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"></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.

1. Abra o painel Gerir e desloque-se até Canais e Incorporação.
2. Em Ligação de demonstração para cliente, escreva o endereço do website (por exemplo, www.theircompany.com).
3. Clique em Copiar para copiar a ligação, ou em Abrir para a ver primeiro.
4. Envie a ligação para quem quiser.

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, consumindo créditos como qualquer outra conversa.
• A página não tem marca. Mostra o website deles e o seu widget, e nada mais.
• Alguns websites não podem ser enquadrados. Vários sites (bancos, grandes retalhistas, qualquer site com definições de segurança rigorosas) impedem que outras páginas os exibam. 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 cumpra o seu propósito.
• Não altera o website deles. Nada é instalado e nada é modificado — a demonstração existe apenas dentro dessa ligação.

A ligação de demonstração utiliza sempre o encaminhamento predefinido da sua conta, independentemente da definição de Encaminhar estes chats para. Se pretender que os chats de demonstração sejam tratados por um agente específico, defina primeiro esse agente como predefinição do seu widget de chat.

Enviar páginas diferentes para campanhas diferentes #

Por predefinição, todos os chats que chegam através do seu widget são tratados pela mesma campanha ou agente. Pode substituir essa definição por página, para que os visitantes na sua página de preços falem com a sua campanha de vendas, enquanto os visitantes na sua página de ajuda falam com o seu agente de apoio — tudo a partir do mesmo widget de chat.

Existem duas formas de obter o código:

• A partir da campanha ou do agente. Na página Campanhas, abra o menu ⋮ numa campanha e escolha Adicionar ao website. Na página Agentes, clique no botão </> na linha, ou abra o agente e vá para o separador Pontos de entrada. Em qualquer um dos casos, obterá um snippet pronto a colar, já direcionado para essa campanha ou 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.

  Adicionar ao site apenas aparece em campanhas que estão ativas e configuradas para processar conversas recebidas. Uma campanha em rascunho ainda não pode receber visitantes, pelo que a opção permanece oculta até que a publique. Na página de Agentes, aparece nos agentes ativos. Um agente em pausa receberia a conversa, mas nunca responderia, pelo que a opção permanece oculta até que a volte a ativar. Não existe nenhum canal a configurar para um agente — um agente pode atender uma conversa de qualquer canal.

• A partir das definições do widget. Em Definições → Canais → Gerir no seu widget de chat, defina Encaminhar estas conversas para e copie o snippet abaixo. Alterar o menu pendente reescreve o snippet.

O snippet flutuante transporta o destino no endereço:

<script src="https://api.youraiconnector.com/v1/chat-widget/CONFIG_ID?campaign=CAMPAIGN_ID"></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-campaign="CAMPAIGN_ID" style="width:100%;height:600px;"></div>
<script src="https://api.youraiconnector.com/v1/chat-widget/embed.js" async></script>

Para um agente, a redação muda para ?agent=AGENT_ID ou data-agent="AGENT_ID".

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 uma campanha ou agente na sua conta, o chat continua a funcionar, mas reverte para o seu encaminhamento predefinido.
• Alguém que já esteja a meio de uma conversa permanece com quem a iniciou, mesmo que mais tarde aceda 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 acionadores 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"></script>

A sua página deve preencher esses valores no lado do servidor, a partir de quem estiver com sessão iniciada.

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 conversa nova em vez de ver o chat da primeira. O widget deteta a mudança de pessoa e reinicia-se.
• Isto serve para contexto, não para iniciar sessão. As conversas continuam a ser mantidas separadas como sempre foram, por isso passar um id nã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í.
• É opcional. Um widget numa página pública normal não precisa de nada disto e comporta-se exatamente como antes.

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:

1. Abra o seu website num navegador.
2. Clique no botão de chat para abrir o widget.
3. Envie uma mensagem de teste e confirme se recebe uma resposta.
4. 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:

1. Certifique-se de que substituiu CONFIG_ID pelo seu identificador de configuração real.
2. Certifique-se de que a etiqueta de script está colocada antes da etiqueta de fecho </body>.
3. Verifique o código quanto a erros de digitação.

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.