O widget da Web é um cliente baseado na Web que pode ser usado em aplicativos para Web e dispositivos móveis para que os usuários interajam com o aplicativo do agente usando chat ou voz. Este guia oferece uma visão geral e instruções de configuração.
Quando aberto, o widget pode ser exibido como uma janela de diálogo flutuante no canto inferior direito, como um painel ao lado do conteúdo principal ou aberto em um modo de diálogo expandido para uma conversa focada.
Limitações
No momento, as respostas com conteúdo avançado só estão disponíveis em inglês.
Configurar o widget da Web
Para incorporar o widget ao seu site:
- Clique em Implantar na parte de cima do criador de agentes.
- Clique em Criar canal ou Novo canal.
- Selecione o tipo de canal Widget da Web.
- Insira um nome para o canal.
- Selecione ou crie uma versão do aplicativo do agente.
- Configure outras preferências, como o tema de cores e o tipo de experiência (chat, chamada ou mista).
- Clique em Criar canal para gerar seu código de implantação.
- Adicione o código de implantação ao HTML do seu site.
- Configure a autenticação para seus usuários finais. O widget mostra um aviso se você usar o código de incorporação sem modificações sem configurar a autenticação. Para detalhes sobre opções e configuração, consulte a seção Configurar autenticação.
Incorpore o widget ao seu site
Para adicionar o widget ao seu site, inclua os seguintes snippets HTML.
O snippet abaixo inclui um script necessário para o reCAPTCHA. Se o reCAPTCHA for usado no widget, uma notificação vai aparecer na parte de baixo dele indicando que o site é protegido pelo Google e que a Política de Privacidade do Google e os Termos de Serviço se aplicam. Também é possível ocultar o selo do reCAPTCHA.
Para oferecer suporte a layouts responsivos, você também pode carregar chat-messenger-layout.css.
O arquivo chat-messenger-layout.css é usado para estilização responsiva
e para deslizar o messenger para dentro e para fora da visualização
ao usar render-mode="slide-in" ou render-mode="slide-over".
Como ele estiliza body,
isso pode afetar seu site.
Portanto, você pode optar por não carregar chat-messenger-layout.css ou copiar o conteúdo e integrar ao seu próprio CSS.
Para ter o melhor desempenho e garantir layouts responsivos, siga estas posições:
Na seção <header>:
<header>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script defer src="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/chat-messenger.js"></script>
<!-- Chat Messenger CSS -->
<link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-default.css">
<!-- Optional responsive styling -->
<!-- <link rel="stylesheet" href="https://www.gstatic.com/ces-console/fast/chat-messenger/prod/v1/themes/chat-messenger-layout.css"> -->
<!-- CSS customization -->
<style>
chat-messenger {
z-index: 999;
position: fixed;
<!-- Your CSS customization goes here if needed -->
}
</style>
</header>
Na seção <body>:
<body>
<!-- Your website's main content goes here -->
<script>
window.addEventListener("chat-messenger-loaded", () => {
chatSdk.registerContext(
chatSdk.prebuilts.ces.createContext({
deploymentName: "projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID",
tokenBroker: {
enableTokenBroker: true,
// If you enabled reCAPTCHA for the token broker, set enableRecaptcha to true.
// enableRecaptcha: true,
},
// Automatically prompt the agent to start the conversation with a greeting.
enableWelcomeEvent: true,
}),
);
});
</script>
<!-- Messenger component -->
<chat-messenger
language-code="en"
max-query-length="-1">
<chat-messenger-chat-bubble
chat-title="${your-chat-title}">
</chat-messenger-chat-bubble>
</chat-messenger>
<!-- Page content continues -->
</body>
Iniciar a conversa automaticamente
Por padrão, o widget de chat espera que o usuário envie a primeira mensagem. Para pedir que o agente inicie a conversa automaticamente com uma saudação, defina enableWelcomeEvent: true na função chatSdk.prebuilts.ces.createContext.
Quando essa opção está ativada, o widget envia automaticamente um evento welcome ao agente quando a sessão de chat é inicializada. O agente responde a esse evento com a saudação configurada.
Considerações sobre segurança
Ao incorporar o widget como um elemento personalizado
(<chat-messenger>)
diretamente no seu site,
ele é executado em um
DOM shadow
na página host.
Ele não aplica o sandbox estrito (como um iframe) por padrão.
Porque o widget compartilha a origem da janela com seu aplicativo:
- Acesso ao armazenamento compartilhado:qualquer script em execução no componente personalizado do widget
tem acesso a
window.sessionStorageewindow.localStorageda página host. Isso inclui tokens de autenticação ou dados sensíveis da sessão armazenados pelo próprio widget. - Scripting em vários sites (XSS): se o código do componente personalizado ou os payloads de conteúdo avançado contiverem entradas não higienizadas, eles poderão ser explorados para executar JavaScript arbitrário no contexto do seu aplicativo principal.
Para manter a segurança do seu aplicativo e dos dados dos usuários, você precisa:
- Limpar o código personalizado:garanta que todo o JavaScript e HTML personalizados usados em componentes ou payloads personalizados sejam rigorosamente limpos.
- Validar entradas:trate todos os dados transmitidos ao widget de fontes externas (incluindo respostas do agente) como não confiáveis.
- Isolamento de manipuladores:se os requisitos de segurança exigirem isolamento estrito entre o widget de chat e os dados do aplicativo, implemente seu próprio sandbox (por exemplo, encapsulando o componente do widget em um contêiner que você controla e isola).
Configurar a transferência para um agente humano
Antes de configurar o widget, verifique se os recursos necessários foram criados e se a implantação do proxy do WebChat foi concluída.
- Defina o número de encaminhamento.
- Crie um recurso PhoneNumber para seu projeto.
- Use um perfil de conversa válido configurado para o aplicativo do agente.
- Associe o perfil de conversa ao PhoneNumber para permitir que o sistema processe o encaminhamento para um humano.
- Siga as instruções para configurar o proxy do WebChat.
- Crie um recurso PhoneNumber para seu projeto.
Configuração do cliente de webchat:
Defina o atributo do WebChat Proxy para ativar o recurso de transferência para atendente. Exemplo de snippet de código:
<chat-messenger service='{"name":"ces","deployment-id":"projects/YOUR_PROJECT_ID/locations/YOUR_REGION/apps/YOUR_APP_ID/deployments/YOUR_DEPLOYMENT_ID"}' liveHandoff="true" escalationNumber="projects/YOUR_PROJECT_ID/locations/global/phoneNumbers/YOUR_PHONE_NUMBER_ID" url-allowlist="*" > </chat-messenger>
Personalização de HTML
Você pode personalizar vários aspectos de como a caixa de diálogo de chat aparece e se comporta.
Os elementos HTML chat-messenger e chat-messenger-container têm os seguintes atributos:
| Atributo | Atribuição de componente | Valor (opcional) | Efeito |
|---|---|---|---|
| serviço | chat-messenger | O nome do serviço necessário para o serviço de back-end conectado. | |
| url-allowlist | chat-messenger | * | (lista de domínios de imagens separados por vírgulas |
| logging-level | chat-messenger | DEPURAR | <OMIT> |
| enable-audio-input-only | chat-messenger-container | Modo somente voz | |
| start-with-recording | chat-messenger-container | Requer o modo somente voz. O modo somente voz começa assim que o chat-messenger-container é renderizado. | |
| enable-audio-input | chat-messenger-container | Adiciona um botão para permitir o chat multimodal | |
| enable-file-upload | chat-messenger-container | Permite uploads de imagens | |
| bot-writing-image | chat-messenger-container | string | URL da imagem renderizada durante o "pensamento" do bot. |
| chat-title-icon | chat-messenger-container | string | URL da imagem renderizada na parte de cima do chat (imagem da marca). |
| chat-title | chat-messenger-container | string | Texto para o título do chat |
| render-mode | chat-messenger | string ("slide-in" ou "slide-over") | O modo de renderização da caixa de diálogo de chat em relação ao restante da página. As opções são "slide-over" ou "slide-in". Se não for especificado, o posicionamento poderá ser especificado pelo cliente. Os estilos são necessários para oferecer suporte ao modo de renderização. chat-messenger-layout.css pode ser usado como uma linha de base. |
Personalização de CSS
A personalização da aparência do widget é feita por um sistema de tokens CSS. Ao modificar esses tokens, você garante que a interface de chat seja consistente com sua marca, mantendo a integridade e a acessibilidade do layout.
Tokens de cor
Esses tokens definem a paleta de cores para as superfícies de widgets, elementos interativos, texto e estados.
| Propriedade | Descrição | Tema claro padrão | Tema escuro padrão |
|---|---|---|---|
| Contêineres / plataformas | |||
| --chat-messenger-color--surface | A cor principal do fundo para o corpo do chat e a área do rodapé. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | A cor de segundo plano dos contêineres de widgets (por exemplo, cards de produtos e carrosséis) aninhados no chat. | #FFFFFF | #131314 |
| --chat-messenger-color--surface-container-high | Um plano de fundo de alta ênfase para elementos em widgets (por exemplo, campos de entrada) | #F0F4F9 | #1E1F20 |
| Marca / Sotaque | |||
| --chat-messenger-color--primary | Cor principal da marca usada para preenchimentos de alta ênfase e botões principais. | #303030 | #E3E3E3 |
| --chat-messenger-color--primary-container | Cor de segundo plano em destaque para componentes principais, como balões de mensagens do usuário. | #E9EEF6 | #282A2C |
| --chat-messenger-color--secondary | Cor para elementos interativos secundários, como o botão "Enviar" ou botões tonais. | #DDE3EA | #333537 |
| Texto e ícones | |||
| --chat-messenger-color--on-surface | Cor primária para texto e ícones mostrados em planos de fundo de superfície padrão. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-surface-variant | Cor de menor ênfase para texto secundário e ícones decorativos. | #444746 | #C4C7C5 |
| --chat-messenger-color--on-primary | Cor para texto e ícones colocados sobre planos de fundo da marca principal. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Cor para texto e ícones colocados sobre planos de fundo de contêineres primários. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Cor para texto e ícones colocados sobre planos de fundo secundários da marca. | #444746 | #C4C7C5 |
| Estados | |||
| --chat-messenger-color--state-layer-on-surface | A sobreposição translúcida usada para indicar estados de passar o cursor ou seleção em superfícies padrão. O preenchimento para componentes desativados. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | A sobreposição translúcida usada para estados de interação acima de elementos coloridos primários. | #FFFFFF 8% | #062E6F 8% |
| --chat-messenger-color--state-layer-on-secondary | A sobreposição translúcida usada para estados de interação sobre elementos de cor secundária. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-on-surface-mute | Cor para texto e ícones desativados. | #444746 (38%) | #C4C7C5 (38%) |
| Utilitário | |||
| --chat-messenger-color--outline | Cor para bordas gerais, divisores e contornos decorativos. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Cor para bordas sutis (por exemplo, a estrutura externa dos widgets) | #747775 com 16% | #8E918F a 16% |
| --chat-messenger-color--outline-active | Cor da borda para campos de entrada e menus suspensos quando estão em foco ou ativos. | #747775 | #8E918F |
| --chat-messenger-color--error | Cor chamativa em contraste com a superfície para preenchimentos, ícones e texto, indicando urgência. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Cor de preenchimento do segundo plano para banners de erro ou contêineres de alerta interativos. | #F9DEDC | #8C1D18 |
| --chat-messenger-color--on-error-container | Texto e ícones colocados no plano de fundo do contêiner de erro. | #8C1D18 | #F9DEDC |
| --chat-messenger-color--link | Cor usada para hiperlinks clicáveis em mensagens ou descrições. | #0B57D0 | #A8C7FA |
Tokens de forma e elevação
Esses tokens controlam o raio do canto e a profundidade visual (sombras) dos componentes de chat.
| Propriedade | Descrição | Padrão |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Raio do canto para pequenos elementos aninhados em widgets (por exemplo, miniaturas de imagens de produtos) | 8px |
| --chat-messenger-shape--corner-value-medium | Raio do canto para elementos aninhados em widgets (por exemplo, campos de entrada, imagens) | 16px |
| --chat-messenger-shape--corner-value-large | Raio do canto para contêineres aninhados em widgets (por exemplo, cards de carrossel, cards de ações rápidas) | 20px |
| --chat-messenger-shape--corner-value-extra-large | Raio do canto para a janela principal de chat e os contêineres de widgets. | 28 px |
| --chat-messenger-shape--corner-fully-rounded | Usado para botões e elementos interativos em forma de pílula para garantir uma extremidade totalmente circular. | 100 px |
| --chat-messenger-elevation | A caixa de sombra aplicada a elementos flutuantes e ao componente principal de chat. | 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15) |
Tokens de tipografia
Esses tokens definem o tipo de letra e a escala específica (tamanho, peso, espaçamento) usada em toda a interface.
| Propriedade | Uso pretendido | Padrão |
|---|---|---|
| --chat-messenger-font-family | Família de fontes principal | Google Sans |
| Título grande | Cabeçalhos em destaque | |
| --chat-messenger-typescale--title-large-font-size | 18 px | |
| --chat-messenger-typescale--title-large-font-weight | 400 | |
| --chat-messenger-typescale--title-large-line-height | 24px | |
| --chat-messenger-typescale--title-large-letter-spacing | 0 | |
| Mídia do título | Cabeçalhos de seção em widgets. | |
| --chat-messenger-typescale--title-medium-font-size | 16px | |
| --chat-messenger-typescale--title-medium-font-weight | 500 | |
| --chat-messenger-typescale--title-medium-line-height | 24px | |
| --chat-messenger-typescale--title-medium-letter-spacing | 0 | |
| Título pequeno | ||
| --chat-messenger-typescale--title-small-font-size | Subtítulos ou títulos em cards menores. | 14px |
| --chat-messenger-typescale--title-small-font-weight | 500 | |
| --chat-messenger-typescale--title-small-line-height | 20px | |
| --chat-messenger-typescale--title-small-letter-spacing | 0 | |
| Corpo grande | Descrições longas. | |
| --chat-messenger-typescale--body-large-font-size | 16px | |
| --chat-messenger-typescale--body-large-font-weight | 400 | |
| --chat-messenger-typescale--body-large-line-height | 24px | |
| --chat-messenger-typescale--body-large-letter-spacing | 0 | |
| Corpo médio | Texto padrão da interface | |
| --chat-messenger-typescale--body-medium-font-size | 14px | |
| --chat-messenger-typescale--body-medium-font-weight | 400 | |
| --chat-messenger-typescale--body-medium-line-height | 20px | |
| --chat-messenger-typescale--body-medium-letter-spacing | 0 | |
| Corpo pequeno | Metadados e descrições secundárias. | |
| --chat-messenger-typescale--body-small-font-size | 12px | |
| --chat-messenger-typescale--body-small-font-weight | 400 | |
| --chat-messenger-typescale--body-small-line-height | 16px | |
| --chat-messenger-typescale--body-small-letter-spacing | 0,1 | |
| Marcar como grande | Texto em botões e chips de ação principal. | |
| --chat-messenger-typescale--label-large-font-size | 14px | |
| --chat-messenger-typescale--label-large-font-weight | 500 | |
| --chat-messenger-typescale--label-large-line-height | 20px | |
| --chat-messenger-typescale--label-large-letter-spacing | 0 | |
| Mídia do rótulo | Texto do botão secundário e rótulos dos campos | |
| --chat-messenger-typescale--label-medium-font-size | 12px | |
| --chat-messenger-typescale--label-medium-font-weight | 500 | |
| --chat-messenger-typescale--label-medium-line-height | 16px | |
| --chat-messenger-typescale--label-medium-letter-spacing | 0,1 | |
| Marcador pequeno | Microrrótulos e texto do selo | |
| --chat-messenger-typescale--label-small-font-size | 11px | |
| --chat-messenger-typescale--label-small-font-weight | 500 | |
| --chat-messenger-typescale--label-small-line-height | 16px | |
| --chat-messenger-typescale--label-small-letter-spacing | 0,1 |
Tokens de espaçamento
Esses tokens mantêm uma densidade de layout consistente, definindo margens, padding e espaços entre elementos.
| Propriedade | Padrão |
|---|---|
| --chat-messenger-spacing--half | 4px |
| --chat-messenger-spacing--one | 8px |
| --chat-messenger-spacing--one-and-half | 12px |
| --chat-messenger-spacing--two | 16px |
| --chat-messenger-spacing--two-and-half | 20px |
| --chat-messenger-spacing--three | 24px |
| --chat-messenger-spacing--three-and-half | 28 px |
| --chat-messenger-spacing--four | 32px |
Eventos JavaScript
O Messenger aciona uma variedade de eventos para os quais você pode criar
listeners de eventos.
O destino do evento é o elemento chat-messenger.
Para adicionar um listener de eventos ao elemento chat-messenger,
adicione o seguinte código JavaScript,
em que event-type é um dos nomes de eventos descritos nesta seção:
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
Os seguintes tipos de evento são compatíveis:
chat-messenger-loaded: esse evento é acionado quando o elementochat-messengeré totalmente carregado e inicializado.chat-messenger-closechat-messenger-error: esse evento ocorre quando o agente do CES envia um código de status de erro. A estrutura do evento é semelhante a esta:eventId= `chat-messenger-error-v2` event.details { message: string; code: number | undefined; status: number | string; }df-update-cart-count: Esse evento ocorre quando as ações "Adicionar ao carrinho", "Ajustar quantidade do item" e "Excluir item" acontecem nos elementos de conteúdo avançadoproduct_carousel,product_detaileproduct_comparison. A estrutura do evento é semelhante a esta:{ "detail": { "count": <cart_item_count>, } }
Funções JavaScript
O elemento chat-messenger fornece
funções
que você pode chamar para afetar o comportamento dele.
renderCustomEvent
Essa função renderiza uma mensagem de texto, como se ela viesse do aplicativo do agente na forma de uma resposta de texto.
Exemplo:
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');
renderCustomCard
Essa função renderiza um card personalizado, como se ele viesse do aplicativo do agente na forma de uma mensagem de resposta avançada. O formato da resposta do payload personalizado é definido na seção Mensagens de resposta avançada.
Exemplo:
const chatMessenger = document.querySelector('chat-messenger');
const payload = [
{
"type": "info",
"title": "Info item title",
"subtitle": "Info item subtitle",
"image": {
"src": {
"rawUrl": "https://example.com/images/logo.png"
}
},
"actionLink": "https://example.com"
}];
chatMessenger.renderCustomCard(payload);
Configurar a autenticação
Todas as solicitações de API feitas pelo widget da Web aos serviços de back-end do Google precisam ser autenticadas. Isso é feito usando um token de acesso do OAuth 2.0 de curta duração.
A identidade associada a esse token, seja um usuário final ou uma conta de serviço, precisa ter as permissões do IAM necessárias para interagir com o agente.
As subseções restantes descrevem as maneiras de configurar a autenticação.
Configurar um agente de token
Um broker de tokens é um serviço da Web executado no seu projeto Google Cloud e gera um token de acesso em nome de uma conta de serviço de sua propriedade. O widget da Web pode chamar automaticamente o URL do seu broker de tokens no início de uma conversa para receber um token atualizado para usar ao se comunicar com a API do CX Agent Studio.
É possível configurar um broker de tokens de duas maneiras: hospedado pelo Google ou autohospedado.
Hospedado pelo Google
Use o agente de token fornecido pelo Google para permitir o acesso público ao widget de chat:
- Ao criar a implantação e a configuração do widget, ative o acesso público e, opcionalmente, as verificações de origem e reCAPTCHA (recomendado para evitar falsificação e abuso).
- O widget de chat vai solicitar um token de escopo de sessão do broker de token fornecido pelo Google e usá-lo em sessões de chat.
Auto-hospedado
Siga estas etapas para configurar um broker de token autohospedado:
- Crie uma conta de serviço no seu projeto e conceda a ela o papel de cliente da Customer Engagement Suite.
- Implante uma função do Cloud Run functions com o exemplo de código do agente de tokens que fornecemos.
Confira instruções detalhadas passo a passo no repositório de código aberto.
Configurar o OAuth2
Um cliente OAuth2 permite que o widget da Web inicie um fluxo de autenticação para o usuário final. Isso geralmente significa que uma janela de diálogo é aberta, em que o usuário faz login na Conta do Google (ou em outros provedores) e o widget da Web recebe um token para operar em nome do usuário.
Escolha essa opção para exigir que os usuários finais façam login antes de usar o agente, em que as credenciais do usuário são usadas para acessar o aplicativo do agente.
Confira as principais etapas que você precisa seguir:
- No console Google Cloud , acesse o Google Auth Platform e selecione "Clientes".
- Clique em Criar cliente.
- Selecione Aplicativo da Web como o tipo de cliente.
- Insira um nome para o novo cliente.
- Adicione o URL do seu site às origens JavaScript autorizadas e aos URIs de redirecionamento autorizados.
- Clique em Criar e aguarde cinco minutos antes de continuar.
Depois de seguir as etapas, você vai receber um ID do cliente no formato:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Forneça isso no atributo oauth-client-id do componente da Web chat-messenger.
Criar sua própria API de autenticação
Crie sua própria API para processar a autenticação e a autorização
do usuário final, que retorna um token de acesso do Google ou um JWT assinado
com permissão para chamar runSession no seu app.
Para informações sobre como usar a API CX Agent Studio, consulte Acesso à API.