El widget web es un cliente basado en la Web que puedes usar en tus aplicaciones web y para dispositivos móviles para que los usuarios interactúen con tu aplicación de agente a través de chat o voz. En esta guía, se proporciona una descripción general y las instrucciones de configuración.
Cuando se abre, el widget se puede mostrar como una ventana de diálogo flotante en la esquina inferior derecha, como un panel junto al contenido principal o en un modo de diálogo expandido para una conversación enfocada.

Limitaciones
Actualmente, las respuestas de contenido enriquecido solo admiten el idioma inglés.
Configura el widget web
Para incorporar el widget en tu sitio web, sigue estos pasos:
- Haz clic en Implementar en la parte superior del compilador de agentes.
- Haz clic en Crear canal o Canal nuevo.
- Selecciona el tipo de canal Widget web.
- Ingresa un nombre para tu canal.
- Selecciona o crea una versión de la aplicación del agente.
- Configura otras preferencias, como el tema de color y el tipo de experiencia (chat, llamada o mixto).
- Haz clic en Crear canal para generar el código de implementación.
- Agrega el código de implementación al HTML de tu sitio web.
- Configura la autenticación para tus usuarios finales. El widget muestra una advertencia si usas el código de incorporación sin modificar sin configurar la autenticación. Para obtener detalles sobre las opciones y la configuración, consulta la sección Configura la autenticación.
Incorpora el widget en tu sitio web
Para agregar el widget a tu sitio web, debes agregar los siguientes fragmentos HTML.
El siguiente fragmento incluye una secuencia de comandos que se requiere para reCAPTCHA. Si se usa reCAPTCHA en el widget, se mostrará un aviso en la parte inferior del widget en el que se indica que el sitio está protegido por Google y que se aplican la Política de Privacidad de Google y las Condiciones del Servicio de Google. También puedes ocultar la insignia de reCAPTCHA.
Para admitir diseños responsivos, también puedes cargar chat-messenger-layout.css de forma opcional.
El archivo chat-messenger-layout.css se usa para aplicar diseño responsivo
y para deslizar el mensajero dentro y fuera de la vista
cuando se usa render-mode="slide-in" o render-mode="slide-over".
Como aplica diseño a body,
puede afectar tu sitio web.
Por lo tanto, puedes optar por no cargar chat-messenger-layout.css o copiar su contenido y, luego, integrarlo en tu propio CSS.
Para obtener el mejor rendimiento y garantizar diseños responsivos, sigue estas ubicaciones:
En la sección <header>, haz lo siguiente:
<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>
En la sección <body>, haz lo siguiente:
<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 la conversación automáticamente
De forma predeterminada, el widget de chat espera a que el usuario envíe el primer mensaje. Para que el agente inicie la conversación automáticamente con un saludo, configura enableWelcomeEvent: true en la función chatSdk.prebuilts.ces.createContext.
Cuando esta opción está habilitada, el widget envía automáticamente un evento welcome al agente cuando se inicializa la sesión de chat. El agente responde a este evento con su saludo configurado.
Consideraciones de seguridad
Cuando incorporas el widget como un elemento personalizado
(<chat-messenger>)
directamente en tu sitio web,
el widget se ejecuta en un
DOM de sombra
en tu página de host.
No aplica una zona de pruebas estricta (como un iframe) de forma predeterminada.
Debido a que el widget comparte el origen de la ventana con tu aplicación, se aplica lo siguiente:
- Acceso al almacenamiento compartido:
Cualquier secuencia de comandos que se ejecute dentro del componente personalizado del widget
tiene acceso a
window.sessionStorageywindow.localStoragede la página host. Esto incluye tokens de autenticación o datos sensibles de la sesión que almacena el widget. - Secuencias de comandos entre sitios (XSS): Si el código de tu componente personalizado o las cargas útiles de contenido enriquecido contienen entradas no saneadas, se pueden aprovechar para ejecutar JavaScript arbitrario en el contexto de tu aplicación principal.
Para mantener la seguridad de tu aplicación y los datos de tus usuarios, debes hacer lo siguiente:
- Limpia el código personalizado: Asegúrate de que todo el código JavaScript y HTML personalizado que se use en los componentes o las cargas útiles personalizados se limpie de forma rigurosa.
- Valida las entradas: Trata todos los datos que se pasan al widget desde fuentes externas (incluidas las respuestas del agente) como no confiables.
- Controla el aislamiento: Si tus requisitos de seguridad exigen un aislamiento estricto entre el widget de chat y los datos de tu aplicación, debes implementar tu propio entorno de pruebas (por ejemplo, unir el componente del widget en un contenedor que controles y aisles).
Configura la transferencia a un agente humano
Antes de configurar el widget, asegúrate de que se hayan creado los recursos necesarios y de que se haya completado la implementación del proxy de WebChat.
- Configura el número de derivación.
- Crea un recurso PhoneNumber para tu proyecto.
- Usa un perfil de conversación válido configurado para la aplicación del agente.
- Asocia el perfil de conversación con el PhoneNumber para permitir que el sistema controle la derivación a un agente humano.
- Sigue las instrucciones para configurar el proxy de WebChat.
- Crea un recurso PhoneNumber para tu proyecto.
Configuración del cliente de Webchat:
Establece el atributo del proxy de WebChat para habilitar la función de transferencia en vivo. Ejemplo de fragmento 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>
Personalización de HTML
Puedes personalizar varios aspectos de cómo aparece y se comporta el diálogo de chat.
Los elementos HTML chat-messenger y chat-messenger-container tienen los siguientes atributos:
| Atributo | Atribución de componentes | Valor (opcional) | Efecto |
|---|---|---|---|
| servicio | chat-messenger | Es el nombre del servicio obligatorio para el servicio de backend conectado. | |
| url-allowlist | chat-messenger | * | (lista de dominios de imágenes separados por comas) |
| logging-level | chat-messenger | DEPURAR | <OMIT> |
| enable-audio-input-only | chat-messenger-container | Modo de solo voz | |
| start-with-recording | chat-messenger-container | Requiere el modo Solo voz. El modo Solo voz se inicia en el momento en que se renderiza el contenedor de chat-messenger-container | |
| enable-audio-input | chat-messenger-container | Agrega un botón para permitir el chat multimodal. | |
| enable-file-upload | chat-messenger-container | Habilita la carga de imágenes | |
| bot-writing-image | chat-messenger-container | cadena | URL de la imagen que se renderiza mientras el bot "piensa" |
| chat-title-icon | chat-messenger-container | cadena | URL de la imagen que se renderiza en la parte superior del chat (imagen de marca) |
| chat-title | chat-messenger-container | cadena | Texto del título del chat |
| render-mode | chat-messenger | string ("slide-in" o "slide-over") | Es el modo de renderizar el diálogo de chat en relación con el resto de la página. Las opciones son "slide-over" o "slide-in". Si no se especifica, el cliente puede especificar el posicionamiento. Los estilos son obligatorios para admitir el modo de renderización. chat-messenger-layout.css se puede usar como modelo de referencia. |
Personalización de CSS
La personalización de la apariencia del widget se controla a través de un sistema de tokens de CSS. Si modificas estos tokens, puedes asegurarte de que la interfaz de chat sea coherente con tu marca y, al mismo tiempo, mantener la integridad y la accesibilidad del diseño.
Tokens de color
Estos tokens definen la paleta de colores para las superficies del widget, los elementos interactivos, el texto y los estados.
| Propiedad | Descripción | Tema claro predeterminado | Tema oscuro predeterminado |
|---|---|---|---|
| Contenedores y plataformas | |||
| --chat-messenger-color--surface | Es el color de fondo principal del cuerpo del chat y del área del pie de página. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | Es el color de fondo de los contenedores de widgets (por ejemplo, tarjetas de productos y carruseles) anidados en el chat. | #FFFFFF | #131314 |
| --chat-messenger-color--surface-container-high | Un fondo de énfasis alto para los elementos dentro de los widgets (por ejemplo, campos de entrada) | #F0F4F9 | #1E1F20 |
| Marca / Acento | |||
| --chat-messenger-color--primary | Es el color principal de la marca que se usa para los rellenos de énfasis alto y los botones principales. | #303030 | #E3E3E3 |
| --chat-messenger-color--primary-container | Es un color de fondo destacado para componentes clave, como las burbujas de mensajes de los usuarios. | #E9EEF6 | #282A2C |
| --chat-messenger-color--secondary | Es el color de los elementos interactivos secundarios, como el botón "Enviar" o los botones tonales. | #DDE3EA | #333537 |
| Texto e íconos | |||
| --chat-messenger-color--on-surface | Es el color principal para el texto y los íconos que se muestran en los fondos de superficie estándar. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-surface-variant | Color de menor énfasis para el texto secundario y los íconos decorativos. | #444746 | #C4C7C5 |
| --chat-messenger-color--on-primary | Es el color del texto y los íconos que se colocan sobre los fondos de la marca principal. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Es el color del texto y los íconos que se colocan sobre los fondos de contenedores principales. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Es el color del texto y los íconos que se colocan sobre los fondos secundarios de la marca. | #444746 | #C4C7C5 |
| Estados | |||
| --chat-messenger-color--state-layer-on-surface | Es la superposición translúcida que se usa para indicar los estados de selección o de desplazamiento sobre las superficies estándar. Es el relleno de los componentes inhabilitados. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | Es la superposición translúcida que se usa para los estados de interacción sobre los elementos de color primario. | #FFFFFF 8% | #062E6F 8% |
| --chat-messenger-color--state-layer-on-secondary | Es la superposición translúcida que se usa para los estados de interacción sobre los elementos de color secundario. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-on-surface-mute | Es el color del texto y los íconos inhabilitados. | #444746 (38%) | #C4C7C5 (38%) |
| Utilidad | |||
| --chat-messenger-color--outline | Color para bordes generales, divisores y contornos decorativos. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Color para bordes sutiles (por ejemplo, el marco exterior de los widgets) | #747775 al 16% | #8E918F al 16% |
| --chat-messenger-color--outline-active | Es el color del borde de los campos de entrada y los menús desplegables cuando están enfocados o activos. | #747775 | #8E918F |
| --chat-messenger-color--error | Color llamativo contra la superficie para rellenos, íconos y texto, que indica urgencia. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Es el color de relleno de fondo para los banners de error o los contenedores de alertas interactivos. | #F9DEDC | #8C1D18 |
| --chat-messenger-color--on-error-container | Texto e íconos colocados sobre el fondo del contenedor de errores. | #8C1D18 | #F9DEDC |
| --chat-messenger-color--link | Es el color que se usa para los hipervínculos en los que se puede hacer clic en los mensajes o las descripciones. | #0B57D0 | #A8C7FA |
Fichas de forma y elevación
Estos tokens controlan el radio de las esquinas y la profundidad visual (sombras) de los componentes del chat.
| Propiedad | Descripción | Predeterminado |
|---|---|---|
| --chat-messenger-shape--corner-value-small | Radio de esquina para elementos anidados pequeños dentro de widgets (por ejemplo, miniaturas de imágenes de productos) | 8 px |
| --chat-messenger-shape--corner-value-medium | Radio de esquina para elementos anidados dentro de widgets (por ejemplo, campos de entrada, imágenes) | 16 px |
| --chat-messenger-shape--corner-value-large | Radio de esquina para contenedores anidados dentro de widgets (por ejemplo, tarjetas de carrusel, tarjetas de acciones rápidas) | 20 px |
| --chat-messenger-shape--corner-value-extra-large | Es el radio de la esquina de la ventana de chat principal y los contenedores de widgets. | 28 px |
| --chat-messenger-shape--corner-fully-rounded | Se usa para botones y elementos interactivos con forma de píldora para garantizar un extremo completamente circular. | 100 px |
| --chat-messenger-elevation | Es la sombra de cuadro que se aplica a los elementos flotantes y al componente principal del chat. | 0 1px 2px 0 rgba(0,0,0,0.3), 0 2px 6px 2px rgba(0,0,0,0.15) |
Tokens de tipografía
Estos tokens definen el tipo de letra y la escala específica (tamaño, grosor y espaciado) que se usan en toda la interfaz.
| Propiedad | Uso previsto | Predeterminado |
|---|---|---|
| --chat-messenger-font-family | Familia de fuentes principal | Google Sans |
| Título grande | Encabezados destacados | |
| --chat-messenger-typescale--title-large-font-size | 18 px | |
| --chat-messenger-typescale--title-large-font-weight | 400 | |
| --chat-messenger-typescale--title-large-line-height | 24 px | |
| --chat-messenger-typescale--title-large-letter-spacing | 0 | |
| Título mediano | Encabezados de sección dentro de los widgets | |
| --chat-messenger-typescale--title-medium-font-size | 16 px | |
| --chat-messenger-typescale--title-medium-font-weight | 500 | |
| --chat-messenger-typescale--title-medium-line-height | 24 px | |
| --chat-messenger-typescale--title-medium-letter-spacing | 0 | |
| Título pequeño | ||
| --chat-messenger-typescale--title-small-font-size | Subencabezados o títulos dentro de tarjetas más pequeñas | 14px |
| --chat-messenger-typescale--title-small-font-weight | 500 | |
| --chat-messenger-typescale--title-small-line-height | 20 px | |
| --chat-messenger-typescale--title-small-letter-spacing | 0 | |
| Body large | Descripciones largas. | |
| --chat-messenger-typescale--body-large-font-size | 16 px | |
| --chat-messenger-typescale--body-large-font-weight | 400 | |
| --chat-messenger-typescale--body-large-line-height | 24 px | |
| --chat-messenger-typescale--body-large-letter-spacing | 0 | |
| Body medium | Texto de la IU estándar | |
| --chat-messenger-typescale--body-medium-font-size | 14px | |
| --chat-messenger-typescale--body-medium-font-weight | 400 | |
| --chat-messenger-typescale--body-medium-line-height | 20 px | |
| --chat-messenger-typescale--body-medium-letter-spacing | 0 | |
| Texto de cuerpo pequeño | Metadatos y descripciones secundarios | |
| --chat-messenger-typescale--body-small-font-size | 12 px | |
| --chat-messenger-typescale--body-small-font-weight | 400 | |
| --chat-messenger-typescale--body-small-line-height | 16 px | |
| --chat-messenger-typescale--body-small-letter-spacing | 0.1 | |
| Etiqueta grande | Texto dentro de los botones y los chips de acción principales | |
| --chat-messenger-typescale--label-large-font-size | 14px | |
| --chat-messenger-typescale--label-large-font-weight | 500 | |
| --chat-messenger-typescale--label-large-line-height | 20 px | |
| --chat-messenger-typescale--label-large-letter-spacing | 0 | |
| Label medium | Texto del botón secundario y etiquetas de campo | |
| --chat-messenger-typescale--label-medium-font-size | 12 px | |
| --chat-messenger-typescale--label-medium-font-weight | 500 | |
| --chat-messenger-typescale--label-medium-line-height | 16 px | |
| --chat-messenger-typescale--label-medium-letter-spacing | 0.1 | |
| Etiqueta pequeña | Microetiquetas y texto de insignias | |
| --chat-messenger-typescale--label-small-font-size | 11 px | |
| --chat-messenger-typescale--label-small-font-weight | 500 | |
| --chat-messenger-typescale--label-small-line-height | 16 px | |
| --chat-messenger-typescale--label-small-letter-spacing | 0.1 |
Tokens de espaciado
Estos tokens mantienen una densidad de diseño coherente, ya que definen los márgenes, los rellenos y los espacios entre los elementos.
| Propiedad | Predeterminado |
|---|---|
| --chat-messenger-spacing--half | 4 px |
| --chat-messenger-spacing--one | 8 px |
| --chat-messenger-spacing--one-and-half | 12 px |
| --chat-messenger-spacing--two | 16 px |
| --chat-messenger-spacing--two-and-half | 20 px |
| --chat-messenger-spacing--three | 24 px |
| --chat-messenger-spacing--three-and-half | 28 px |
| --chat-messenger-spacing--four | 32 px |
Eventos de JavaScript
Messenger activa una variedad de eventos para los que puedes crear
objetos de escucha de eventos.
El destino de estos eventos es el elemento chat-messenger.
Para agregar un objeto de escucha de eventos para el elemento chat-messenger, agrega el siguiente código de JavaScript, en el que event-type es uno de los nombres de eventos que se describen en esta sección:
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.addEventListener('event-type', function (event) {
// Handle event
...
});
Se admiten los siguientes tipos de eventos:
chat-messenger-loaded: Este evento se activa cuando el elementochat-messengerse carga y se inicializa por completo.chat-messenger-closechat-messenger-error: Este evento se produce cuando el agente de CES envía un código de estado de error. La estructura del evento se ve de la siguiente manera:eventId= `chat-messenger-error-v2` event.details { message: string; code: number | undefined; status: number | string; }df-update-cart-count: Este evento ocurre cuando se realizan las acciones "Agregar al carrito", "Ajustar la cantidad de artículos" o "Borrar artículo" en los elementos de contenido enriquecidoproduct_carousel,product_detailoproduct_comparison. La estructura del evento se ve de la siguiente manera:{ "detail": { "count": <cart_item_count>, } }
Funciones de JavaScript
El elemento chat-messenger proporciona funciones a las que puedes llamar para modificar su comportamiento.
renderCustomText
Esta función renderiza un mensaje de texto, como si proviniera de la aplicación del agente como una respuesta de texto.
Por ejemplo:
const chatMessenger = document.querySelector('chat-messenger');
chatMessenger.renderCustomText('Custom text');
renderCustomCard
Esta función renderiza una tarjeta personalizada, como si proviniera de la aplicación del agente como un mensaje de respuesta enriquecida. El formato de la respuesta de carga útil personalizada se define en la sección Mensajes de respuesta enriquecida.
Por ejemplo:
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);
Configura la autenticación
Todas las solicitudes a la API que realiza el widget web a los servicios de backend de Google deben autenticarse. Esto se logra con un token de acceso de OAuth 2.0 de corta duración.
La identidad asociada con este token, ya sea un usuario final o una cuenta de servicio, debe tener los permisos de IAM necesarios para interactuar con el agente.
En los apartados restantes, se describen las formas en que puedes configurar la autenticación.
Configura un agente de tokens
Un agente de tokens es un servicio web que se ejecuta en tu proyecto de Google Cloud y genera un token de acceso en nombre de una cuenta de servicio de tu propiedad. El widget web puede llamar automáticamente a la URL de tu agente de tokens al comienzo de una conversación para obtener un token nuevo que se usará cuando se comunique con la API de CX Agent Studio.
Puedes configurar un agente de tokens de dos maneras: alojado en Google o alojado de forma independiente.
Alojado en Google
Usa el agente de tokens que proporciona Google para permitir el acceso público a tu widget de chat:
- Cuando crees la configuración de la implementación y del widget, habilita el acceso público y, de manera opcional, habilita las verificaciones de origen y de reCAPTCHA (se recomienda para evitar la falsificación de identidad y el abuso).
- El widget de chat solicitará un token de alcance de sesión al agente de tokens proporcionado por Google y lo usará para las sesiones de chat.
Autoalojado
Sigue estos pasos para configurar un agente de tokens autoalojado:
- Crea una cuenta de servicio en tu proyecto y otórgale el rol de cliente de Paquete de interacción con los clientes.
- Implementa una función de Cloud Run Functions con el código de muestra del agente de tokens que proporcionamos.
Consulta las instrucciones detalladas paso a paso en el repositorio de código abierto.
Configura OAuth2
Un cliente de OAuth2 permite que el widget web inicie un flujo de autenticación para el usuario final. Por lo general, esto significa que se abre una ventana de diálogo en la que el usuario accede a su Cuenta de Google (o a otros proveedores) y el widget web recibe un token para operar en nombre del usuario.
Elige esta opción para exigir que los usuarios finales accedan antes de usar el agente, en el que se usan las credenciales de usuario para acceder a la aplicación del agente.
Estos son los pasos principales que debes seguir:
- En la consola de Google Cloud , ve a Google Auth Platform y selecciona Clientes.
- Haz clic en Crear cliente.
- Selecciona Aplicación web como el tipo de cliente.
- Ingresa un nombre para tu cliente nuevo.
- Agrega la URL de tu sitio web a los Orígenes autorizados de JavaScript y a los URI de redireccionamiento autorizados.
- Haz clic en Crear y espera 5 minutos antes de continuar.
Después de seguir los pasos, obtendrás un ID de cliente con el siguiente formato:
123456789012-abcdefghijklmnopqrstuvwxyz.apps.googleusercontent.com
Proporciona este valor en el atributo oauth-client-id del componente web chat-messenger.
Compila tu propia API de autenticación
Compila tu propia API para controlar la autenticación y autorización
del usuario final, que devuelve un token de acceso de Google o un JWT firmado
que tiene permiso para llamar a runSession en tu app.
Para obtener información sobre cómo usar la API de CX Agent Studio, consulta Acceso a la API.