BotFramework WebChat
[4.18.0] - 2024-07-10
Este repositorio contiene código para el componente Bot Framework Web Chat. El componente Bot Framework Web Chat es un cliente basado en web altamente personalizable para el SDK de Bot Framework v4. Bot Framework SDK v4 permite a los desarrolladores modelar conversaciones y crear aplicaciones de bot sofisticadas.
Este repositorio es parte de Microsoft Bot Framework, un marco integral para crear experiencias de IA conversacional de nivel empresarial.
Web Chat admite la Política de seguridad de contenido (CSP). Se recomienda a los desarrolladores web que habiliten CSP para mejorar la seguridad y proteger las conversaciones. Puede leer más sobre CSP en este artículo.
Esta sección señala notas importantes de la versión. Para obtener más información, consulte los enlaces relacionados y consulte
CHANGELOG.md
Notas: se recomienda a los desarrolladores web que utilicen ~ (rango de tilde) para seleccionar versiones menores, que contienen nuevas características y/o correcciones. Utilice ^ (rango de intercalación) para seleccionar versiones principales, que pueden contener cambios importantes.
En esta versión, nos centramos en mejoras de rendimiento, incluidas optimizaciones de memoria y tiempo de carga.
Los bots ahora pueden transmitir en vivo sus respuestas. Antes de que Bot Framework SDK admita esta función, los autores de bots pueden seguir los detalles en LIVESTREAMING.md para construir las respuestas de la transmisión en vivo.
Web Chat ahora exporta como módulos ES (exportaciones con nombre) junto con CommonJS (exportaciones con nombre y sin nombre).
El usuario final ahora puede agregar un mensaje y confirmar antes de cargar su archivo en el bot. Para optar por no participar en la nueva experiencia, pase sendAttachmentOn: 'send' en las opciones de estilo.
Estamos entusiasmados de agregar compatibilidad con paquetes de temas. Los desarrolladores ahora pueden empaquetar toda su personalización en un solo paquete y publicarlo en NPM.
Nos complace anunciar que el paquete temático Fluent UI está en proceso y actualmente se encuentra en fase experimental. Este paquete de temas está diseñado para desarrolladores web que desean brindar una experiencia de usuario nativa de Copilot a sus clientes.
Continuaremos agregando nuevas funciones y admitiendo tanto la experiencia de marca blanca como la experiencia Fluent UI con el mismo nivel de paridad.
Puede finalizar el chat web con <FluentThemeProvider> para probar la nueva experiencia.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} Web Chat ahora mostrará HTML en Markdown. Hemos adaptado nuestro desinfectante y solucionador de accesibilidad para que funcione en el nivel HTML. Tanto Markdown como HTML-in-Markdown recibirán el mismo tratamiento y cumplirán con nuestros requisitos de seguridad y accesibilidad.
Puede desactivar esta opción configurando styleOptions.markdownRenderHTML en false .
Web Chat ahora admite el esquema de tarjetas adaptables hasta 1.6. Algunas funciones de Tarjetas adaptables están en versión preliminar o están diseñadas para usarse fuera de Bot Framework. Web Chat no admite estas funciones.
A partir de 4.16.0, Internet Explorer ya no es compatible. Después de más de un año desde el retiro oficial de Internet Explorer 11, decidimos dejar de admitir Internet Explorer. Esto nos ayudará a incorporar nuevas funciones al chat web. 4.15.9 es la última versión que admite Internet Explorer de forma limitada.
adaptiveCardsParserMaxVersionEl parche Web Chat 4.12.1 incluye una nueva propiedad de estilo que permite a los desarrolladores elegir la versión máxima del esquema de tarjetas adaptables. Consulte PR #3778 para cambios de código.
Para especificar una versión máxima diferente, puede ajustar las opciones de estilo, que se muestran a continuación:
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ; Se agregó una nueva actualización de accesibilidad al chat web desde el PR #3703. Este cambio crea un enfoque visual para la transcripción (borde negro en negrita) y la actividad enfocada aria-activedescendent (borde negro discontinuo) de forma predeterminada. Cuando corresponda, los valores transcriptVisualKeyboardIndicator... también se aplicarán a los elementos secundarios del carrusel ( CarouselFilmStrip.js ). Esto se hace para que coincida con el estilo de enfoque predeterminado actual para las tarjetas adaptables, que pueden ser hijas de un carrusel.
Para modificar estos estilos, puede cambiar los siguientes accesorios a través de styleOptions :
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
El código anterior muestra los valores predeterminados que verá en el chat web.
La API de Web Chat se ha refactorizado en un paquete independiente. Para obtener más información, consulte el resumen de refactorización de API.
A partir de Web Chat 4.7.0, se admite Direct Line Speech y es la forma preferida de proporcionar una funcionalidad de voz integrada en Web Chat. Estamos trabajando para cerrar las brechas de funciones entre Direct Line Speech y Web Speech API (incluye Cognitive Services y funcionalidad de voz proporcionada por el navegador).
A partir de Web Chat 4.6.0, Web Chat requiere React 16.8.6 o superior.
Aunque le recomendamos que actualice su aplicación host lo antes posible, entendemos que la aplicación host puede necesitar algo de tiempo antes de que se actualicen sus dependencias de React, especialmente en lo que respecta a aplicaciones de gran tamaño.
Si su aplicación aún no está lista para React 16.8.6, puede seguir el ejemplo híbrido de React para tener React de doble host en su aplicación.
Hay un cambio radical en las expectativas de comportamiento con respecto al habla y las sugerencias de entrada en el chat web. Consulte la sección sobre el comportamiento de las sugerencias de entrada antes de 4.5.0 para obtener más detalles.
Vea los documentos de migración para obtener información sobre cómo migrar desde Web Chat v3.
Primero, cree un bot usando Azure Bot Service. Una vez creado el bot, deberá obtener el secreto del chat web del bot en Azure Portal. Luego use el secreto para generar un token y pasarlo a su chat web.
Web Chat proporciona una interfaz de usuario además de los canales Direct Line y Direct Line Speech. Hay dos formas de conectarse a su bot a través de llamadas HTTP desde el cliente: enviando el secreto del Bot o generando un token a través del secreto.
Recomendamos encarecidamente utilizar la API de token en lugar de proporcionar su secreto a la aplicación. Para obtener más información sobre por qué, consulte la documentación de autenticación sobre la API del token y la seguridad del cliente.
Para obtener más información, consulte los siguientes enlaces:
Uso del chat web con autenticación de Azure Bot Services
Funciones mejoradas de autenticación de línea directa
Web Chat está diseñado para integrarse con su sitio web existente mediante JavaScript o React. La integración con JavaScript le brindará opciones moderadas de estilo y personalización.
Puede utilizar el paquete completo y típico de Web Chat (llamado paquete de funciones completas) que contiene las funciones más utilizadas.
A continuación se explica cómo puede agregar control de chat web a su sitio web:
<!DOCTYPE html >
< html >
< head >
< script
crossorigin =" anonymous "
src =" https://cdn.botframework.com/botframework-webchat/latest/webchat.js "
> </ script >
< style >
html,
body {
height: 100%;
}
body {
margin: 0;
}
#webchat {
height: 100%;
width: 100%;
}
</ style >
</ head >
< body >
< div id =" webchat " role =" main " > </ div >
< script >
window . WebChat . renderWebChat (
{
directLine : window . WebChat . createDirectLine ( {
token : 'YOUR_DIRECT_LINE_TOKEN'
} ) ,
userID : 'YOUR_USER_ID' ,
username : 'Web Chat User' ,
locale : 'en-US'
} ,
document . getElementById ( 'webchat' )
) ;
</ script >
</ body >
</ html >
userID,usernameylocaleson parámetros opcionales para pasar al métodorenderWebChat. Para obtener más información sobre los accesorios de Web Chat, consulte la documentación de referencia de la API de Web Chat.
No se recomienda asignar
userIDcomo un valor estático, ya que esto hará que todos los usuarios compartan el estado. Consulte laAPI userID entrypara obtener más información.
Puede encontrar más información sobre la localización en la documentación de localización.
Vea la muestra funcional del paquete completo de chat web.
Para una personalización total, puede utilizar React para recomponer componentes de Web Chat.
Para instalar la compilación de producción desde NPM, ejecute npm install botframework-webchat . Consulte nuestras notas de versión sobre cómo seleccionar una versión.
import React , { useMemo } from 'react' ;
import ReactWebChat , { createDirectLine } from 'botframework-webchat' ;
export default ( ) => {
const directLine = useMemo ( ( ) => createDirectLine ( { token : 'YOUR_DIRECT_LINE_TOKEN' } ) , [ ] ) ;
return < ReactWebChat directLine = { directLine } userID = "YOUR_USER_ID" / > ;
} ;También puede ejecutar
npm install botframework-webchat@mainpara instalar una compilación de desarrollo que esté sincronizada con la ramamainde GitHub de Web Chat.
Vea la muestra funcional de Web Chat renderizada a través de React.
Web Chat utiliza internamente Redux para la gestión del estado. Redux DevTools está habilitado en la compilación de NPM como una función de participación voluntaria.
Esto es para echar un vistazo a cómo funciona el chat web. Este no es un explorador de API y no respalda el uso de la tienda Redux para acceder mediante programación a la interfaz de usuario. En su lugar, se debe utilizar la API de ganchos.
Para usar Redux DevTools, use la función createStoreWithDevTools para crear una tienda habilitada para Redux DevTools.
import React, { useMemo } from 'react';
- import ReactWebChat, { createDirectLine, createStore } from 'botframework-webchat';
+ import ReactWebChat, { createDirectLine, createStoreWithDevTools } from 'botframework-webchat';
export default () => {
const directLine = useMemo(() => createDirectLine({ token: 'YOUR_DIRECT_LINE_TOKEN' }), []);
- const store = useMemo(() => createStore(), []);
+ const store = useMemo(() => createStoreWithDevTools(), []);
return <ReactWebChat directLine={directLine} store={store} userID="YOUR_USER_ID" />;
};Existen algunas limitaciones al utilizar Redux DevTools:
redux-saga . Viajar en el tiempo puede dañar la interfaz de usuario.Web Chat está diseñado para ser personalizable sin bifurcar el código fuente. La siguiente tabla describe qué tipo de personalizaciones puede lograr al importar Web Chat de diferentes maneras. Esta lista no es exhaustiva.
| paquete CDN | Reaccionar | |
|---|---|---|
| cambiar colores | ✔ | ✔ |
| Cambiar tallas | ✔ | ✔ |
| Actualizar/reemplazar estilos CSS | ✔ | ✔ |
| Escuchar eventos | ✔ | ✔ |
| Interactuar con la página web de alojamiento | ✔ | ✔ |
| Actividades de renderizado personalizadas | ✔ | |
| Archivos adjuntos de renderizado personalizados | ✔ | |
| Agregar nuevos componentes de interfaz de usuario | ✔ | |
| Recomponer toda la interfaz de usuario | ✔ |
Vea más sobre cómo personalizar Web Chat para obtener más información sobre la personalización.
Bot Framework tiene muchos tipos de actividades, pero no todas son compatibles con Web Chat. Vea documentos sobre tipos de actividades para obtener más información.
Vea la lista completa de ejemplos de Web Chat para obtener más ideas sobre cómo personalizar Web Chat.
Vea la documentación de API para implementar Web Chat.
Web Chat admite las 2 últimas versiones de navegadores modernos como Chrome, Microsoft Edge y FireFox. Si necesita Web Chat en Internet Explorer 11, consulte la demostración del paquete ES5.
Tenga en cuenta, sin embargo:
babel . Ver la documentación de accesibilidad.
Vea la documentación de localización para implementar en Web Chat.
Vea la documentación de notificación para implementar en Web Chat.
Vea la documentación de telemetría para implementar en Web Chat.
Consulte la Guía de soporte técnico para obtener orientación y ayuda sobre la solución de problemas en el repositorio de Web Chat para obtener más información antes de presentar un nuevo problema.
Web Chat admite una amplia gama de motores de voz para una experiencia de chat natural con un bot. Esta sección describe los diferentes motores compatibles:
Direct Line Speech es la forma preferida de agregar funcionalidad de voz en Web Chat. Consulte la documentación de Direct Line Speech para obtener más detalles.
Puede utilizar los servicios de voz de Cognitive Services para agregar funcionalidad de voz al chat web. Consulte la documentación de los servicios del habla de Cognitive Services para obtener más detalles.
También puede utilizar cualquier motor de voz que admita el estándar W3C Web Speech API. Algunos navegadores admiten la API de reconocimiento de voz y la API de síntesis de voz. Puede mezclar y combinar diferentes motores, incluidos los servicios de voz de Cognitive Services, para brindar la mejor experiencia de usuario.
Las últimas novedades de Web Chat están disponibles en la página de lanzamientos diarios de Web Chat.
Los diarios se publicarán después de las 3:00 a. m., hora estándar del Pacífico, cuando se hayan confirmado los cambios en la rama principal.
Consulte nuestra página de contribución para obtener detalles sobre cómo construir el proyecto y nuestras pautas de repositorio para solicitudes de extracción.
Consulte nuestra página CÓDIGO DE CONDUCTA para obtener detalles sobre el Código de conducta de Microsoft.
Consulte la documentación de seguridad para obtener más información sobre cómo informar problemas de seguridad.
