O widget da Web é um cliente baseado na Web que pode ser usado em aplicativos da Web e para 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 em um modo de diálogo expandido para uma conversa focada.

Limitações
No momento, as respostas de 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, ligação ou mista).
- Clique em Criar canal para gerar o código de implantação.
- Adicione o código de implantação ao HTML do seu site.
- Configure a autenticação para os usuários finais. O widget vai mostrar um aviso se você usar o código de incorporação não modificado sem configurar a autenticação. Para detalhes sobre opções e configuração, consulte a seção Configurar autenticação.
Incorporar o widget ao seu site
Para adicionar o widget ao seu site, inclua os snippets de HTML a seguir.
O snippet abaixo inclui um script necessário para o reCAPTCHA. Se o reCAPTCHA for usado no widget, um aviso será exibido na parte de baixo do widget indicando que o site está protegido pelo Google e que a Política de Privacidade do Google e os Termos de Serviço do Google se aplicam. Também é possível ocultar o selo reCAPTCHA.
Para oferecer suporte a layouts responsivos, também é possível carregar
chat-messenger-layout.css.
O arquivo chat-messenger-layout.css é usado para estilizar a responsividade
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,
pode afetar seu site.
Portanto, você pode optar por não carregar chat-messenger-layout.css
ou copiar o conteúdo e integrá-lo 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/chat-messenger/sdk/prod/latest/chat-messenger.js"></script>
<!-- Chat Messenger CSS -->
<link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/themes/chat-messenger-default.css">
<!-- Optional responsive styling -->
<!-- <link rel="stylesheet" href="https://www.gstatic.com/chat-messenger/sdk/prod/latest/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 o usuário enviar a primeira mensagem. Para 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
shadow DOM
na página do host.
Ele não aplica o sandbox estrito (como um iframe) por padrão.
Como o widget compartilha a origem da janela com seu aplicativo:
- Acesso ao armazenamento compartilhado:todos os scripts em execução no componente personalizado do widget
têm acesso a
window.sessionStorageewindow.localStorageda página host. Isso inclui tokens de autenticação ou dados de sessão sensíveis 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 limpas, eles poderão ser explorados para executar JavaScript arbitrário no contexto do aplicativo principal.
Para manter a segurança do aplicativo e dos dados dos usuários, você precisa:
- Limpar o código personalizado:verifique se todo o JavaScript e HTML personalizados usados em componentes ou payloads personalizados estão devidamente limpos.
- Validar entradas:trate todos os dados transmitidos ao widget de fontes externas (incluindo respostas do agente) como não confiáveis.
- Gerenciar o isolamento:se os requisitos de segurança exigirem um isolamento rigoroso entre o widget de chat e os dados do aplicativo, você precisará implementar seu próprio sandbox (por exemplo, encapsular o componente do widget em um contêiner que você controla e isola).
Configurar o encaminhamento para 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.
- Configure 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 lide com o encaminhamento para um atendente 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 proxy do WebChat para ativar o recurso de transferência em tempo real. 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
É possível personalizar vários aspectos da aparência e do comportamento da caixa de diálogo do chat.
Os elementos HTML chat-messenger e chat-messenger-container
têm os seguintes atributos:
| Atributo | Atribuição de componentes | Valor (opcional) | Efeito |
|---|---|---|---|
| serviço | chat-messenger | O nome do serviço obrigatório para o serviço de back-end conectado. | |
| url-allowlist | chat-messenger | * | (lista separada por vírgulas de domínios de imagem |
| 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 é iniciado no segundo em 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 | Ativa o upload 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 do título da conversa |
| render-mode | chat-messenger | string ("slide-in" ou "slide-over") | O modo de renderização da caixa de diálogo do 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 um valor de referência. |
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 do 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 do widget, 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 plano de fundo do corpo do chat e da área do rodapé. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | A cor de fundo 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 / Destaque | |||
| --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 fundo de destaque para componentes importantes, 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 principal para texto e ícones exibidos 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 os planos de fundo principais da marca. | #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 passagem do 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 sobre elementos de cor primária. | #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ários | |||
| --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 moldura externa de widgets) | #747775 com 16% | #8E918F a 16% |
| --chat-messenger-color--outline-active | Cor da borda dos campos de entrada e menus suspensos quando estão em foco ou ativos. | #747775 | #8E918F |
| --chat-messenger-color--error | Cor que chama a atenção em relação à superfície para preenchimentos, ícones e texto, indicando urgência. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Cor de preenchimento do plano de fundo 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 do chat.
| Propriedade | Descrição | Padrão |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Raio de 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 da janela de chat principal e dos contêineres de widget. | 28 px |
| --chat-messenger-shape--corner-fully-rounded | Usado para botões e elementos interativos em formato de pílula para garantir uma extremidade totalmente circular. | 100 px |
| --chat-messenger-elevation | A sombra de caixa aplicada aos elementos flutuantes e ao componente principal do 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 a família tipográfica 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 | |
| Título médio | 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 | |
| Body medium | 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ários. | |
| --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 | |
| Rótulo grande | Texto em botões e ícones 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 | |
| Rótulo médio | Texto do botão secundário e rótulos de campo | |
| --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 | |
| Rótulo 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, preenchimentos e espaços entre os 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 vários eventos para os quais você pode criar
listeners de eventos.
O destino desses eventos é 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 evento 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 de itens" 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.
renderCustomText
Essa função renderiza uma mensagem de texto, como se ela viesse do aplicativo do agente como 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 viesse do aplicativo do agente como 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 para os 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 agente de token é um serviço da Web executado no projeto do Google Cloud e gera um token de acesso em nome de uma conta de serviço que pertence a você. O widget da Web pode chamar automaticamente o URL do seu agente de token no início de uma conversa para receber um novo token que será usado na comunicação com a API CX Agent Studio.
É possível configurar um agente de token de duas maneiras: hospedado pelo Google ou auto-hospedado.
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, se quiser, as verificações de origem e do reCAPTCHA (recomendado para evitar spoofing e abuso).
- O widget de chat vai solicitar um token de escopo de sessão do agente de token fornecido pelo Google e usá-lo para sessões de chat.
Auto-hospedado
Siga estas etapas para configurar um agente de token auto-hospedado:
- Crie uma conta de serviço no seu projeto e conceda a ela o papel de cliente do Pacote de engajamento do cliente.
- Implante uma função do Cloud Run functions com o exemplo de código do agente de token que fornecemos.
Confira instruções detalhadas 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 de 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 do Google Cloud , acesse a Plataforma Google Auth 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 5 minutos antes de continuar.
Depois de seguir as etapas, você vai receber um ID do cliente no formato:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Informe 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 app.
Para informações sobre como usar a API CX Agent Studio, consulte Acesso à API.