BotFramework WebChat
[4.18.0] - 2024-07-10
Este repositório contém código para o componente Bot Framework Web Chat. O componente Bot Framework Web Chat é um cliente baseado na Web altamente personalizável para o SDK do Bot Framework v4. O Bot Framework SDK v4 permite que os desenvolvedores modelem conversas e criem aplicativos de bot sofisticados.
Este repositório faz parte do Microsoft Bot Framework – uma estrutura abrangente para a construção de experiências de IA conversacional de nível empresarial.
O Web Chat oferece suporte à Política de Segurança de Conteúdo (CSP). Recomenda-se que os desenvolvedores da Web habilitem o CSP para melhorar a segurança e proteger as conversas. Você pode ler mais sobre CSP neste artigo.
Esta seção destaca notas importantes da versão. Para mais informações, consulte os links relacionados e verifique o
CHANGELOG.md
Notas: os desenvolvedores web são aconselhados a usar ~ (intervalo de til) para selecionar versões secundárias, que contêm novos recursos e/ou correções. Use ^ (intervalo de intercalação) para selecionar versões principais, que podem conter alterações significativas.
Nesta versão, estamos nos concentrando em melhorias de desempenho, incluindo otimizações de memória e tempo de carregamento.
Os bots agora podem transmitir suas respostas ao vivo. Antes do Bot Framework SDK oferecer suporte a esse recurso, os autores do bot podem seguir os detalhes em LIVESTREAMING.md para construir as respostas de transmissão ao vivo.
O Web Chat agora exporta como módulos ES (exportações nomeadas) junto com CommonJS (exportações nomeadas e não nomeadas).
O usuário final agora pode adicionar uma mensagem e confirmar antes de enviar o arquivo para o bot. Para cancelar a nova experiência, passe sendAttachmentOn: 'send' nas opções de estilo.
Estamos entusiasmados em adicionar suporte para pacotes temáticos. Os desenvolvedores agora podem agrupar todas as suas personalizações em um único pacote e publicá-lo no NPM.
Temos o prazer de anunciar que o pacote de temas Fluent UI está em desenvolvimento e atualmente em fase experimental. Este pacote de temas foi projetado para desenvolvedores web que desejam trazer uma experiência de usuário nativa do Copilot para seus clientes.
Continuaremos adicionando novos recursos e oferecendo suporte tanto à experiência de marca branca quanto à experiência de UI Fluent com o mesmo nível de paridade.
Você pode encerrar o Web Chat com <FluentThemeProvider> para experimentar a nova experiência.
import ReactWebChat from 'botframework-webchat' ;
import { FluentThemeProvider } from 'botframework-webchat-fluent-theme' ;
export default function MyComponent ( ) {
return (
< FluentThemeProvider >
< ReactWebChat / >
< / FluentThemeProvider >
) ;
} O Web Chat agora renderizará HTML em Markdown. Portamos nosso desinfetante e fixador de acessibilidade para funcionar no nível HTML. Tanto o Markdown quanto o HTML-in-Markdown receberão o mesmo tratamento e atenderão aos nossos requisitos de segurança e acessibilidade.
Você pode desativar esta opção definindo styleOptions.markdownRenderHTML como false .
O Web Chat agora oferece suporte ao esquema de Cartões Adaptáveis até 1.6. Alguns recursos dos Cartões Adaptáveis estão em versão prévia ou foram projetados para uso fora do Bot Framework. O Web Chat não oferece suporte a esses recursos.
A partir da versão 4.16.0, o Internet Explorer não é mais compatível. Depois de mais de um ano da aposentadoria oficial do Internet Explorer 11, decidimos parar de oferecer suporte ao Internet Explorer. Isso nos ajudará a trazer novos recursos para o Web Chat. 4.15.9 é a última versão que oferece suporte ao Internet Explorer de forma limitada.
adaptiveCardsParserMaxVersionO patch do Web Chat 4.12.1 inclui uma nova propriedade de estilo que permite aos desenvolvedores escolher a versão máxima do esquema de Adaptive Cards. Consulte PR #3778 para alterações de código.
Para especificar uma versão máxima diferente, você pode ajustar as opções de estilo mostradas abaixo:
window . WebChat . renderWebChat (
{
directLine ,
store ,
styleOptions : {
adaptiveCardsParserMaxVersion : '1.2'
}
} ,
document . getElementById ( 'webchat' )
) ; Uma nova atualização de acessibilidade foi adicionada ao Web Chat do PR #3703. Essa alteração cria foco visual para a transcrição (borda preta em negrito) e atividade focada aria-activedescendent (borda preta tracejada) por padrão. Quando aplicável, os valores transcriptVisualKeyboardIndicator... também serão aplicados aos filhos do carrossel ( CarouselFilmStrip.js ). Isso é feito para corresponder ao estilo de foco padrão atual dos Cartões Adaptáveis, que podem ser filhos de um carrossel.
Para modificar esses estilos, você pode alterar os seguintes adereços via styleOptions :
transcriptActivityVisualKeyboardIndicatorColor: DEFAULT_SUBTLE,
transcriptActivityVisualKeyboardIndicatorStyle: 'dashed',
transcriptActivityVisualKeyboardIndicatorWidth: 1,
transcriptVisualKeyboardIndicatorColor: 'Black',
transcriptVisualKeyboardIndicatorStyle: 'solid',
transcriptVisualKeyboardIndicatorWidth: 2,
O código acima mostra os valores padrão que você verá no Web Chat.
A API do Web Chat foi refatorada em um pacote separado. Para saber mais, confira o resumo do refatorador da API.
A partir do Web Chat 4.7.0, a Fala em Linha Direta é suportada e é a forma preferida de fornecer uma funcionalidade de fala integrada no Web Chat. Estamos trabalhando para preencher lacunas de recursos entre Direct Line Speech e Web Speech API (inclui Serviços Cognitivos e funcionalidade de fala fornecida pelo navegador).
A partir do Web Chat 4.6.0, o Web Chat requer React 16.8.6 ou superior.
Embora recomendemos que você atualize seu aplicativo host o mais rápido possível, entendemos que o aplicativo host pode precisar de algum tempo antes que suas dependências React sejam atualizadas, especialmente em relação a aplicativos grandes.
Se seu aplicativo ainda não estiver pronto para o React 16.8.6, você pode seguir o exemplo do React híbrido para o React de host duplo em seu aplicativo.
Há uma mudança significativa nas expectativas de comportamento em relação à fala e às dicas de entrada no Web Chat. Consulte a seção sobre comportamento de dicas de entrada antes da versão 4.5.0 para obter detalhes.
Veja os documentos de migração para saber mais sobre a migração do Web Chat v3.
Primeiro, crie um bot usando o Azure Bot Service. Depois que o bot for criado, você precisará obter o segredo do Web Chat do bot no Portal do Azure. Em seguida, use o segredo para gerar um token e passá-lo para o seu Web Chat.
O Web Chat fornece UI além dos canais Direct Line e Direct Line Speech. Existem duas maneiras de se conectar ao seu bot por meio de chamadas HTTP do cliente: enviando o segredo do Bot ou gerando um token por meio do segredo.
É altamente recomendável usar a API do token em vez de fornecer seu segredo ao aplicativo. Para saber mais sobre o motivo, consulte a documentação de autenticação na API do token e na segurança do cliente.
Para ler mais, consulte os seguintes links:
Usando o Web Chat com autenticação do Azure Bot Services
Recursos aprimorados de autenticação Direct Line
O Web Chat foi projetado para integração com seu site existente usando JavaScript ou React. A integração com JavaScript lhe dará opções moderadas de estilo e personalização.
Você pode usar o pacote completo e típico do Web Chat (chamado de pacote completo de recursos) que contém os recursos mais usados.
Veja como você pode adicionar o controle do Web Chat ao seu site:
<!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,usernameelocalesão parâmetros opcionais para passar para o métodorenderWebChat. Para saber mais sobre os adereços do Web Chat, consulte a documentação de referência da API do Web Chat.
Atribuir
userIDcomo um valor estático não é recomendado, pois isso fará com que todos os usuários compartilhem o estado. Consulte aAPI userID entrypara obter mais informações.
Mais informações sobre localização podem ser encontradas na documentação de localização.
Veja o exemplo funcional do pacote completo do Web Chat.
Para personalização total, você pode usar React para recompor componentes do Web Chat.
Para instalar a compilação de produção do NPM, execute npm install botframework-webchat . Veja nossas notas de versão sobre como selecionar uma versão.
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" / > ;
} ;Você também pode executar
npm install botframework-webchat@mainpara instalar uma compilação de desenvolvimento que seja sincronizada com o branchmaindo GitHub do Web Chat.
Veja o exemplo funcional do Web Chat renderizado via React.
O Web Chat usa Redux internamente para gerenciamento de estado. Redux DevTools está habilitado na construção do NPM como um recurso opcional.
Isto é para dar uma olhada em como funciona o Web Chat. Este não é um explorador de API e não é um endosso ao uso da loja Redux para acessar programaticamente a IU. A API hooks deve ser usada em seu lugar.
Para usar Redux DevTools, use a função createStoreWithDevTools para criar um armazenamento habilitado 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" />;
};Existem algumas limitações ao usar o Redux DevTools:
redux-saga . A viagem no tempo pode quebrar a IU.O Web Chat foi projetado para ser personalizável sem bifurcar o código-fonte. A tabela abaixo descreve que tipo de personalizações você pode obter ao importar o Web Chat de diferentes maneiras. Esta lista não é exaustiva.
| Pacote CDN | Reagir | |
|---|---|---|
| Alterar cores | ✔ | ✔ |
| Alterar tamanhos | ✔ | ✔ |
| Atualizar/substituir estilos CSS | ✔ | ✔ |
| Ouça os eventos | ✔ | ✔ |
| Interaja com a página de hospedagem | ✔ | ✔ |
| Atividades de renderização personalizadas | ✔ | |
| Anexos de renderização personalizados | ✔ | |
| Adicione novos componentes de UI | ✔ | |
| Recomponha toda a IU | ✔ |
Veja mais sobre como personalizar o Web Chat para saber mais sobre personalização.
O Bot Framework tem muitos tipos de atividades, mas nem todos são compatíveis com o Web Chat. Veja a documentação sobre tipos de atividades para saber mais.
Veja a lista completa de exemplos de Web Chat para obter mais ideias sobre como personalizar o Web Chat.
Veja a documentação da API para implementar o Web Chat.
O Web Chat oferece suporte às 2 versões mais recentes de navegadores modernos, como Chrome, Microsoft Edge e FireFox. Se você precisar do Web Chat no Internet Explorer 11, consulte a demonstração do pacote ES5.
Observe, no entanto:
babel . Veja a documentação de acessibilidade.
Veja a documentação de localização para implementação no Web Chat.
Veja a documentação de notificação para implementação no Web Chat.
Veja a documentação de telemetria para implementação no Web Chat.
Consulte o Guia de suporte técnico para obter orientação e ajuda na solução de problemas no repositório do Web Chat para obter mais informações antes de registrar um novo problema.
O Web Chat oferece suporte a uma ampla variedade de mecanismos de fala para uma experiência de bate-papo natural com um bot. Esta seção descreve os diferentes mecanismos suportados:
A Fala em Linha Direta é a forma preferida de adicionar funcionalidade de fala no Web Chat. Consulte a documentação do Direct Line Speech para obter detalhes.
Você pode usar os Serviços de Fala dos Serviços Cognitivos para adicionar funcionalidade de fala ao Web Chat. Consulte a documentação dos Serviços de Fala dos Serviços Cognitivos para obter detalhes.
Você também pode usar qualquer mecanismo de fala que suporte o padrão W3C Web Speech API. Alguns navegadores oferecem suporte à API de reconhecimento de fala e à API de síntese de fala. Você pode combinar diferentes mecanismos – incluindo Serviços de Fala de Serviços Cognitivos – para fornecer a melhor experiência do usuário.
Os últimos bits do Web Chat estão disponíveis na página de lançamentos diários do Web Chat.
Os diários serão divulgados após as 3h, horário padrão do Pacífico, quando as alterações forem confirmadas na filial principal.
Consulte nossa página de contribuição para obter detalhes sobre como construir o projeto e nossas diretrizes de repositório para solicitações pull.
Consulte nossa página CÓDIGO DE CONDUTA para obter detalhes sobre o Código de Conduta da Microsoft.
Consulte a documentação de segurança para saber mais sobre como relatar problemas de segurança.
