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 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 mixta).
- Haz clic en Crear canal para generar tu 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 de código 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 que 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 el diseño responsivo y para deslizar el Messenger dentro y fuera de la vista cuando se usa render-mode="slide-in" o render-mode="slide-over".
Como le aplica un 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 e 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/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>
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 solicitarle al agente que 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 el 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 host.
No aplica una zona de pruebas estricta (como un iframe) de forma predeterminada.
El widget comparte el origen de la ventana con tu aplicación por los siguientes motivos:
- 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 de sesión sensibles 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 sin limpiar, 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 los 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 cargas útiles personalizados se limpie de forma rigurosa.
- Valida las entradas: Considera que todos los datos que se pasan al widget desde fuentes externas (incluidas las respuestas del agente) no son de confianza.
- Aislamiento de controladores: 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 espacio aislado (por ejemplo, envolviendo el componente del widget en un contenedor que controles y aísles).
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.
- Número de derivación de la configuració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 número de teléfono para permitir que el sistema controle la derivación humana.
- Sigue las instrucciones para configurar WebChat Proxy.
- Crea un recurso PhoneNumber para tu proyecto.
Configuración del cliente de chat web:
Establece el atributo desde el 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 sobre cómo aparece y se comporta el cuadro de 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 requerido 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 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 mensajería de chat. | |
| enable-audio-input | chat-messenger-container | Se agregó un botón para permitir el chat multimodal | |
| enable-file-upload | chat-messenger-container | Permite subir imágenes | |
| bot-writing-image | chat-messenger-container | cadena | URL de la imagen renderizada durante el "pensamiento" del bot |
| chat-title-icon | chat-messenger-container | cadena | URL de la imagen renderizada 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 | cadena ("slide-in" o "slide-over") | Es el modo de renderización del cuadro de 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 la posición. Se requieren estilos para admitir el modo de renderización. chat-messenger-layout.css se puede usar como 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 se sienta 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 de los widgets, 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 y el pie de página del chat. | #F8FAFD | #1B1B1B |
| --chat-messenger-color--surface-container | Es el color de fondo de los contenedores de widgets (por ejemplo, las tarjetas de productos y los carruseles) anidados dentro del chat. | #FFFFFF | #131314 |
| --chat-messenger-color--surface-container-high | Un fondo de alta importancia para los elementos dentro de los widgets (por ejemplo, los campos de entrada) | #F0F4F9 | #1E1F20 |
| Marca o acento | |||
| --chat-messenger-color--primary | 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 | Color de fondo destacado para componentes clave, como las burbujas de mensajes del usuario | #E9EEF6 | #282A2C |
| --chat-messenger-color--secondary | Color para elementos interactivos secundarios, como el botón “Enviar” o los botones tonales. | #DDE3EA | #333537 |
| Texto y los íconos | |||
| --chat-messenger-color--on-surface | Color principal para el texto y los íconos que se muestran sobre 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 | Color para el texto y los íconos colocados sobre los fondos de la marca principal. | #F2F2F2 | #303030 |
| --chat-messenger-color--on-primary-container | Color para el texto y los íconos que se colocan sobre los fondos de primary-container. | #1F1F1F | #E3E3E3 |
| --chat-messenger-color--on-secondary | Color para el texto y los íconos que se colocan sobre los fondos de la marca secundaria. | #444746 | #C4C7C5 |
| Estados | |||
| --chat-messenger-color--state-layer-on-surface | Es la capa superpuesta translúcida que se usa para indicar los estados de selección o cuando se coloca el cursor sobre un elemento en superficies estándar. Es el relleno de los componentes inhabilitados. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-layer-on-primary | Es la capa superpuesta 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 capa superpuesta translúcida que se usa para los estados de interacción sobre elementos con color secundario. | #1F1F1F 8% | #E3E3E3 8% |
| --chat-messenger-color--state-on-surface-mute | Color para el texto y los íconos inhabilitados. | #444746 (38%) | #C4C7C5 (38%) |
| Utilidad | |||
| --chat-messenger-color--outline | Color para bordes, divisores y contornos decorativos generales. | #C4C7C5 | #444746 |
| --chat-messenger-color--outline-variant | Color para bordes sutiles (por ejemplo, el marco exterior de los widgets) | #747775 al 16% | #8E918F con un 16% |
| --chat-messenger-color--outline-active | 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 sobre la superficie para rellenos, íconos y texto, que indica urgencia. | #B3261E | #F2B8B5 |
| --chat-messenger-color--error-container | Color de relleno de fondo para los banners de error o los contenedores de alertas interactivas. | #F9DEDC | #8C1D18 |
| --chat-messenger-color--on-error-container | Texto e íconos colocados sobre el fondo de error-container. | #8C1D18 | #F9DEDC |
| --chat-messenger-color--link | Color que se usa para los hipervínculos en los que se puede hacer clic dentro de los mensajes o las descripciones. | #0B57D0 | #A8C7FA |
Tokens 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 pequeños anidados 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 | Radio de esquina para 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 en forma de píldora para garantizar un extremo completamente circular. | 100 px |
| --chat-messenger-elevation | Sombra de caja aplicada 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, peso, espaciado) que se usa 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 | |
| Medio del título | 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 | Subtítulos o títulos dentro de tarjetas más pequeñas | 14 px |
| --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 grandes | |
| --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 | |
| Cuerpo del medio | Texto de la IU estándar | |
| --chat-messenger-typescale--body-medium-font-size | 14 px | |
| --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 | |
| Body small | 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 principal. | |
| --chat-messenger-typescale--label-large-font-size | 14 px | |
| --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 | |
| Etiqueta del medio | Texto del botón secundario y etiquetas de los campos | |
| --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 márgenes, padding y espacios entre 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 del evento para estos eventos es el elemento chat-messenger.
Si deseas agregar un objeto de escucha de eventos al elemento chat-messenger, agrega el siguiente código 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-messengerestá cargado por completo y ya inicializado.chat-messenger-closechat-messenger-error: Este evento ocurre cuando el agente de CES envía un código de estado de error. La estructura del evento tiene el siguiente aspecto:eventId= `chat-messenger-error-v2` event.details { message: string; code: number | undefined; status: number | string; }df-update-cart-count: Este evento se produce cuando se realizan las acciones "Agregar al carrito", "Ajustar la cantidad del artículo" y "Borrar artículo" en los elementos de contenido enriquecidoproduct_carousel,product_detailyproduct_comparison. La estructura del evento tiene el siguiente aspecto:{ "detail": { "count": <cart_item_count>, } }
Funciones de JavaScript
El elemento chat-messenger proporciona funciones a las que puedes llamar para modificar su comportamiento.
renderCustomEvent
Esta función renderiza un mensaje de texto, como si viniera 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 viniera 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 estar autenticadas. 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 las subsecciones 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 Google Cloud y genera un token de acceso en nombre de una cuenta de servicio que te pertenece. 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 autoalojado.
Alojado en Google
Usa el agente de tokens proporcionado por Google para permitir el acceso público a tu widget de chat:
- Cuando crees la implementación y la configuración del widget, habilita el acceso público y, de manera opcional, habilita las verificaciones de origen y de reCAPTCHA (se recomienda para evitar la suplantación 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 autohospedado:
- Crea una cuenta de servicio en tu proyecto y otórgale el rol de cliente de Customer Engagement Suite.
- 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 requerir que los usuarios finales accedan antes de usar el agente, en cuyo caso se usarán las credenciales del 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 Clients.
- 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 JavaScript autorizados 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 esta información en el atributo oauth-client-id del componente web chat-messenger.
Compila tu propia API de autenticación
Crea tu propia API para controlar la autenticación y la 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.