WebChat BotFramework

Clique aqui para saber as novidades do Web Chat

Bate-papo na Web da estrutura do bot

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.

---

Notas de versão

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.

4.19.0 mudanças notáveis

• Suporta mensagem informativa em transmissão ao vivo

4.18.0 mudanças notáveis

Nesta versão, estamos nos concentrando em melhorias de desempenho, incluindo otimizações de memória e tempo de carregamento.

4.17.0 mudanças notáveis

Suporta resposta de transmissão ao vivo

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.

Estreia dos Módulos ES

O Web Chat agora exporta como módulos ES (exportações nomeadas) junto com CommonJS (exportações nomeadas e não nomeadas).

Melhoria na experiência de upload de arquivos

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.

Suporte para pacote temático

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.

Pacote de temas Experimental Fluent UI

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 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 >
   ) ;
} 

Suporte HTML em Markdown

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 .

4.16.1 mudanças notáveis

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.

4.16.0 mudanças notáveis

A partir da versão 4.16.0, o Internet Explorer não é mais compatível. Após 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.

Patch 4.12.1: Nova propriedade de estilo adaptiveCardsParserMaxVersion

O 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 Cartões Adaptáveis. 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' )
) ;

• O Web Chat aplicará o esquema máximo disponível de acordo com a versão dos Cartões Adaptáveis ​​(a partir deste patch, esquema 1.3) por padrão.
• Uma versão inválida reverterá para o padrão do Web Chat.

O foco visual muda para transcrição no Web Chat 4.12.0

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.

Refatoração de API em novo pacote no Web Chat 4.11.0

A API do Web Chat foi refatorada em um pacote separado. Para saber mais, confira o resumo do refatorador da API.

Suporte para fala em linha direta no Web Chat 4.7.0

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).

Atualizando para 4.6.0

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.

Mudanças de fala no Web Chat 4.5.0

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.

Migrando do Web Chat v3 para v4

Veja a documentação de migração para saber mais sobre a migração do Web Chat v3.

---

Como usar

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.

Conecte um aplicativo cliente ao bot

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

Integrar com JavaScript

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:

">

 >
< 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 , username e locale são parâmetros opcionais para passar para o método renderWebChat . Para saber mais sobre os adereços do Web Chat, consulte a documentação de referência da API do Web Chat.

Atribuir userID como um valor estático não é recomendado, pois isso fará com que todos os usuários compartilhem o estado. Consulte a API userID entry para 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.

Integrar com React

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@main para instalar uma compilação de desenvolvimento que seja sincronizada com o branch main do GitHub do Web Chat.

Veja o exemplo funcional do Web Chat renderizado via React.

Suporte experimental para Redux DevTools

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 ;
  };

Existem algumas limitações ao usar o Redux DevTools:

• A loja Redux usa efeitos colaterais via redux-saga . A viagem no tempo pode quebrar a IU.
• Muitos estados da UI são armazenados no contexto e estado do React. Eles não estão expostos na loja Redux.
• Algumas UIs sensíveis ao tempo são baseadas no relógio em tempo real e não são afetadas pela viagem no tempo.
• As ações de despacho não são oficialmente suportadas. Em vez disso, use a API de ganchos.
• Ações e redutores podem entrar e sair da loja Redux entre versões. API Hooks é a API oficial para acessar a UI.

Personalizando a IU do Web Chat

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.

Tipos de atividades suportadas no cliente de webchat

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.

Lista de amostras

Veja a lista completa de exemplos de Web Chat para obter mais ideias sobre como personalizar o Web Chat.

Leitura adicional

Referência de API

Veja a documentação da API para implementar o Web Chat.

Compatibilidade do navegador

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:

• O Web Chat não oferece suporte ao Internet Explorer anterior à versão 11
• A personalização mostrada em exemplos não ES5 não é suportada pelo Internet Explorer. Como o IE11 é um navegador não moderno, ele não suporta ES6, e muitos exemplos que usam funções de seta e promessas modernas precisariam ser convertidos manualmente para ES5. Se você precisar de muita personalização para seu aplicativo, recomendamos fortemente desenvolvê-lo para um navegador moderno como Google Chrome ou Microsoft Edge.
• O Web Chat não tem planos de oferecer suporte a amostras para IE11 (ES5).
  • Para clientes que desejam reescrever manualmente nossos outros exemplos para funcionar no IE11, recomendamos a conversão de código de ES6+ para ES5 usando polyfills e transpilers como babel .

Acessibilidade

Veja a documentação de acessibilidade.

Localização

Veja a documentação de localização para implementação no Web Chat.

Notificações

Veja a documentação de notificação para implementação no Web Chat.

Telemetria

Veja a documentação de telemetria para implementação no Web Chat.

Guia de suporte técnico

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.

Discurso

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:

• Discurso de Linha Direta
• Serviços Cognitivos Serviços de Fala
• Mecanismo fornecido pelo navegador ou outros mecanismos

Integrar com fala em linha direta

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.

Integrar com serviços de fala de serviços cognitivos

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.

Mecanismo fornecido pelo navegador ou outros mecanismos

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.

---

Como testar com as últimas novidades do Web Chat

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.

Contribuindo

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.

Relatando problemas de segurança

Consulte a documentação de segurança para saber mais sobre como relatar problemas de segurança.