Add Web Chat FAQ

FAQs

Web Chat secret / token management

The following link provides several examples on token management: Web Chat secret management

Receive "TypeError: Super expression must either be null or a function" on < 4.6.0

In short, speech is being enabled in an environment that denied access to microphone.

For details, please read #2855.

• Web Chat < 4.6.0: The error message was incorrectly showing "Super expression must either be null or a function". Instead, it should say, speech recognition/synthesis cannot be enabled because microphone access is denied.

• Web Chat >= 4.6.0: We have fixed the error message.

The following environment does not support microphone access and speech should not be enabled.

• Mobile iOS apps
• Hosting in <IFRAME> on Chrome/Edge/Firefox without Feature Policy set
• Hosting on insecure HTTP
• IE11

Receive E401 when running npm install botframework-webchat on or after 4.9.2

On >= 4.9.2, running npm install botframework-webchat results in E401.

This happen if you are using a custom registry which require authentication. And you authenticate using a per-project .npmrc file.

Background

npx will pick up the registry on ./.npmrc, but it can't pick up the token there. It can only pick up the token at ~/.npmrc.

Workaround

Instead of authenticating on ./.npmrc file (local project .npmrc), please authenticate against ~/.npmrc (per-user .npmrc file).

The actual location of ~/.npmrc can be found by running npm config get userconfig.

Related issues

There is an issue filed to Azure DevOps about inconsistent handling of .npmrc file, https://github.com/microsoft/azure-pipelines-tasks/issues/13265, it usually lead to this issue.

Update activity renderer

The custom activity renderer will pass multiple arguments. When sending the arguments downstream, please make sure all the arguments are sent by using rest operators. For example:

const activityMiddleware = () => next => (...args) => {
  return next(...args);
};

Questions need to formalize into a section

Do we want to provide a frequently asked questions document on this repo? Team, please add to the list below of topics that would be added to the FAQ

• IE11
  • create-react-app or other NPM-based app
    • Devs would need to install polyfills required by Web Chat, otherwise, IE11 will not able to load the page
    • Today, the dev will need to copy polyfills from index-es5.ts
    • Tomorrow, they should be able to just import botframework-webchat/ie11 to load the polyfill (#2511)
• ES5
• Samples
• User messages being added to top of conversation (due to computer being behind 'real' time)
• Custom Speech
  • https://github.com/compulim/web-speech-cognitive-services#custom-speech-support
  • User need to pass
    • Subscription key (or authorization token)
    • Endpoint ID (not to be confused with endpoint URL)
• Custom Voice
  • https://github.com/compulim/web-speech-cognitive-services#custom-voice-support
  • User need to pass
    • Subscription key (or authorization token)
    • Deployment ID (not to be confused with deployment/endpoint URL)
    • Voice model name
• Biased word list (a.k.a. dynamic phrases)
  • Set SpeechGrammarList.phrases to an array of strings
• Header in Web Chat window
• https://github.com/Microsoft/BotFramework-WebChat/issues/465 Web Chat shows retry but message is still sent to bot
• Why speech works in Edge but not Chrome
  • Because IFRAME in Chrome put restrictions on microphone unless lifted, the feature is called Feature Policy. And this new feature is not implemented in current version of Edge, thus, it's not blocked.
• Why speech recognition works in other browsers but not Firefox
  • You should see HTTP 400 in Network tab when speech recognition is making the call to wss://*.stt.speech.microsoft.com
  • Firefox defaulted language to en instead of en-US (and fr instead of fr-FR). Cognitive Services did not recognize this type of language, thus it return HTTP errors when it trying to recognize using en
  • You should explicitly set the language when instantiating Web Chat so speech recognition will use the defined language other than en or fr
• Why speech recognition is not working in Angular on Web Chat 4.6.0+
  • See #2957
  • Angular use zone.js
  • zone.js polyfilled Object.defineProperties regardless the browser natively implemented it or not
  • The implementation has a flaw filed in 2016, outlined in https://github.com/angular/angular/issues/31750
  • The bug caused spread operator to fail on a inserting a Symbol-based key into an object
    • The key was Symbol.iterator, and it failed to insert into an object to make it iterable
  • Workaround: in Angular, un-polyfill Object.defineProperties so the app no longer use the flawed implementation
• Why message is not in right order on Dynamics 365 Portal
  • Dynamics 365 Portal polluted the hosting environment and broke various functions related to Date object
  • Please use <IFRAME> to embed Web Chat, before putting it on Dynamics 365 Portal
  • If <IFRAME> is not a viable solution, please submit a support ticket to Dynamics 365 Portal team
  • Related to #2633
• Why ABC\nDEF is on the same line? And ABC\n\n\nDEF only have a single line break between them?
  • Web Chat default render all messages using Markdown, thus, it render <p>ABC DEF</p> and <p>ABC</p><p>DEF</p> respectively
  • To override this behavior, explicitly set textFormat to plain on the bot response
• #872 Typing indicator did not send on polling-based connection, only send on Web Socket
  • They get filtered on the server side
• #2306 - Change Web Chat default font size
• https://github.com/microsoft/BotFramework-WebChat/issues/2479 - consume latest bits in a .js file
• https://github.com/microsoft/BotFramework-WebChat/issues/2563 Deleting/Editing an activity in the transcript
• https://github.com/microsoft/BotFramework-WebChat/issues/2568 Speech synthesis behavior
• https://github.com/microsoft/BotFramework-WebChat/issues/2580 Custom styling hero cards
• https://github.com/microsoft/BotFramework-WebChat/issues/2602 Reasons for no longer supporting React < 16.8
• https://github.com/microsoft/BotFramework-WebChat/issues/2120#issuecomment-516056614 - Welcome messages. See also welcome message documentation in /docs
• https://github.com/microsoft/BotFramework-WebChat/issues/2614 #2556 Scroll to bottom manually (say on button click)
• https://github.com/microsoft/BotFramework-WebChat/issues/2761 Direct Line polling
• https://github.com/microsoft/BotFramework-WebChat/issues/2885 adaptive card button title is truncated - can modify via Adaptive Cards host config
• https://github.com/microsoft/BotFramework-WebChat/issues/2921 shared user state and assigning userID
• Why single quote (') become 3 diamond-question marks (a.k.a. tofu) instead?
  • Probably you are using Web Chat via NPM
  • Web Chat use Markdown-It to render most activities
  • Markdown-It have smart apostrophe, which turns single quote (') into apostrophe (’)
  • Your bundler which bundle Web Chat, output UTF-8
  • Your web server did not specify charset when serving your app bundle
    • MIME type of text/javascript is not correct
    • The correct one is text/javascript; charset=utf-8
  • Thus, the browser use codepage from the webpage, probably CP-437 (ASCII)
  • Apostrophe in UTF-8 is E2 80 99 (hex)
  • Thus, when rendered in ASCII, it become 3 tofu
  • To fix, apply one of the following:
    • On your web server, set the MIME type for your bundle file to text/javascript; charset=utf-8
    • On your Webpack configuration, set the Terser configuration output.ascii_only to true
      • This will turn E2 80 99 (hex) into \u00E2\u0080\u0099 in your JS file
• Why it took > 30 seconds to see the first message from the bot?
  • Open F12 dev tools and click on "Network" tab
  • Click the HTTP traffic with URL /stream?, which is the Web Socket connection to Azure Bot Services
    • It is normal to see the status is "Pending", because the Web Socket connection is still open. If this turns into a number, that means the Web Socket connection is closed
  • On the "Preview" tab on the right hand side, check if it show any responses from the server
  • If only request but no response, that means the browser is connecting to the Azure Bot Services
    • If there is response, that means the connection to ABS is ready, you should check your bot
  • Possible reasons if taking too much time to connect to ABS:
    1. The browser is trying to connect to directline.botframework.com so many times that the Web Socket connection get queued (connection pooling and browser-side DDoS protection)
       • Some observations: when running Fiddler, everything works fine
    2. Network is slow
• Why it took > 30s to load webchat-es5.js in a browser?
  • If you are loading the file and rendering it on the screen, it will be slow because the file is large and is single line
  • You should use cURL to verify the asset instead, e.g. cURL -l -L -o nul -H "Accept: *" https://cdn.botframework.com/botframework-webchat/latest/webchat-es5.js
• https://github.com/microsoft/BotFramework-WebChat/issues/3526#issuecomment-705199136 More details on recomposing the UI
  • https://github.com/microsoft/BotFramework-WebChat/issues/3490
• https://github.com/microsoft/BotFramework-WebChat/issues/3533#issuecomment-707375354 Accessibility: Focus does not change to most recent activity (as activities are populated in the transcript)
• https://github.com/microsoft/BotFramework-WebChat/issues/3627 DL ASE Web Socket error 500 - set up web.config and 'always on'
• Ponyfill vs polyfill https://github.com/microsoft/BotFramework-WebChat/issues/2371
• Changing timestamp format: https://github.com/microsoft/BotFramework-WebChat/issues/3701
• Inline PDF viewer https://github.com/microsoft/BotFramework-WebChat/issues/3404
• Speech bot for iOS (Safari) must not be in silent mode https://github.com/microsoft/BotFramework-WebChat/issues/3381

Start by reviewing the existing documentation in /docs and the FAQ topics listed in this issue. Determine which questions belong in a maintained FAQ and how related issue links should be organized; done means the agreed FAQ content is documented without leaving the listed topics ambiguous.