Skip to content

Instantly share code, notes, and snippets.

@corinagum

corinagum/TSG.md

Last active January 4, 2021 21:29
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save corinagum/af6345698649c8f921ccd3512d411e01 to your computer and use it in GitHub Desktop.
Save corinagum/af6345698649c8f921ccd3512d411e01 to your computer and use it in GitHub Desktop.
Download ZIP
Step-by-step guide on debugging Web Chat problems
Raw
TSG.md

Web Chat Technical Support Guide

This guide is intended to help users:

  1. Find answers when facing a problem, (e.g. bug or implementation issue) and/or
  2. Find feature requests and discussion related to their current topic

before filing a new issue. This will help users discover answers and/or workarounds without needing to wait for a response, and will help the Web Chat team reproduce a reported bug more quickly.

Table of Contents

  1. Determining a Web Chat concern
  2. Searching samples
  3. Searching documentation
  4. Searching FAQ
  5. Searching the issues list
  6. Reporting a bug
  7. Making a feature request
  8. Reporting a new FAQ
  9. Supporting material

Determining a Web Chat concern

First, you want to confirm that your question/concern/bug is related to Web Chat. If it is not, you will be better served searching for answers in another place.

The question is NOT related to Web Chat if:

  1. You are not using Web Chat
    1. Are you using Microsoft Teams or another channel for your bot? If yes, you will probably not find helpful information here
  2. Your topic is in regards to bot implementation, not the Web Chat client. You can use the following links as appropriate:
    1. For implementation questions, search/post a question on Stack Overflow Bot Framework tag
    2. For BotFramework SDK bugs:
      1. BotBuilder .Net repository
      2. BotBuilder JavaScript repository
      3. BotBuilder Python repository
      4. BotBuilder Java repository
  3. Your bug involves an Adaptive Card that you can reproduce on the Adaptive Cards Designer
    1. To test your card in the Designer, copy-paste your card's json into the designer. If this card looks the same as your card in Web Chat, see the next bullet image: Copy-paste your card's json in the Adaptive Cards designer
    2. To report an Adaptive Cards bug, search the Adaptive Cards repository
  4. Your bug exists in other parts of your app/website (not just Web Chat)
  5. Note: Web Chat implementation questions should be redirected to Stack Overflow
    1. Search samples for technical guidance of common Web Chat features
    2. For implementation questions, search/post a question on Stack Overflow Web Chat tag

The question IS related to Web Chat if:

  1. The topic is related to the bot UI
  2. You are following a Web Chat sample or tutorial and discover a problem
  3. You are bumping your version of Web Chat and notice a behavior change from code that worked previously
  4. You can reproduce the bug in one browser (e.g. Microsoft Edge) but not another (e.g. Google Chrome)
    1. Note: this may be a browser bug, and therefore not Web Chat's domain to fix/implement and will need to be reported to the appropriate team
  5. The topic is Accessibility, and the problem only occurs in Web Chat
    1. Note: this may be an Assistive Technology (e.g. Windows Narrator, JAWS, NVDA, etc.) bug, and therfore not Web Chat's domain to fix/implement and will need to be reported to the appropriate team
      1. Windows Narrator
      2. Accessibility Insights
      3. JAWS
      4. NVDA
      5. Voiceover
      6. TalkBack
  6. The topic is related to speech.
    1. Note: this may be a speech bug (DL Speech, Cognitive Services, web browser speech), and therefore not Web Chat's domain to fix/implement and will need to be reported to the appropriate team
      1. DirectLine Speech
      2. Cognitive Services Speech SDK
      3. Web Speech API

Searching samples

For common implementation scenarios, the Web Chat repository includes a list of samples that may jumpstart your development.

Searching documentation

Feel free to peruse our documentation, which is sorted based on general topic. These docs include design decisions, implementation quirks, links to related topics, and more.

Searching FAQ

Web Chat has several commonly-asked questions, workarounds, and known dependency issues that may address the problem you are currently investigating. If a question comes up more than once, the Web Chat team adds the related issue to the FAQ list for easier perusal.

  1. Navigate to the FAQ
  2. Search for keywords related to your question (e.g. iOS, speech, or Dynamics 365)
    1. Use the brower's search function by pressing Ctrl + F (Windows) or Cmd + F (OSX) image: search for keywords
  3. Read the high-level information written in the FAQ. If you want more information, click the related link (as applicable) image: Follow related links
  4. If your FAQ search doesn't produce results, try different keywords, as there may be many ways the question has been asked previously
  5. If you find an issue that discusses or resolves your problem, please chime in with a thumbsup or comment on that issue.
  6. If you haven't found what you are looking for, please move on to searching the issues list

Searching issues

The issues page is where all Web Chat-related discussion is tracked on GitHub. If you did not find something in the FAQ, you may still find it in issues because: a) This topic has not come up multiple times yet, b) It has not yet been added to the FAQ, or c) this topic has already been addressed in a previous discussion, bugfix, or new feature merge

  1. Navigate to Web Chat's issues page
  2. Using the searchbar, delete the text is:open from the searchbar
  3. In the searchbar, type the keywords related to your topic image: Use the issues search feature
  4. For more information on how to search through issues, see the GitHub search documentation
  5. To add a topic to the FAQ, see Add a new FAQ

You can also look for issues by topic:

If you find an issue that discusses or resolves your problem, please chime in with a thumbsup or comment on that issue.

If this section did not help you, please move on to reporting a bug or making a feature request

Reporting a bug

Please note that the more visual detail, code, and implementation steps you provide will allow us to assist you more quickly

Before posting your bug, be sure to remove or hide all PII (Personally identifiable information) in your screenshots, code, and details

  1. Begin by filing a new issue as a bug image: File a new issue
  2. Fill out each section as thoroughly as possible
    1. The more detail you can provide us, the more quickly we can help you image: Fill out each section of the bug report
      1. Screenshots
      2. Version
        • The version of Web Chat in your app is required for all bug reports. This helps us quickly test the problem you are experiencing in the correct environment.
        • See the information inside the creating a bug dialog for how to determine your version of Web Chat
      3. Describe the bug
        • List the environment details of where you are experiencing this bug as applicable, including:
          • Browser
          • Host app (JS, React, Angular, etc)
          • OS (Windows, iOS, etc)
        • List the console errors you are seeing, if any (screenshots of these also help)
        • Describe the bug as specifically as possible
        • Network activity
      4. Steps to reproduce
        • Provide a detailed step-by-step of how the bug is experienced (required). Be sure to include:
          • Typed or spoken commands
          • Dialog interactions (e.g. button clicks)
        • Provide the environment that reproduces the bug (required; see options below)
          1. Link to a 'basic bot' that reproduces your specific issue.
            • This is the easiest way of avoiding the accidental exposure of PII, and guarantees that we can reproduce your issue.
          2. Link to your existing bot (removing all PII)
          3. Provide the settings and command(s) that reproduce the bug on the WebChat Playground
        • If your bug is related to an Adaptive Card, please provide your card's json (with PII removed)
        • If your bug is related to an incoming activity, please provide the activity details (with PII removed)
      5. Expected behavior
      6. Additional context (more info is better!)
      • Include links to any related samples, issues, pull requests, or documentation

Making a feature request

Once you have determined that your desired enhancement has not been requested yet, feel free to make the request yourself.

  1. Begin by filing a new issue as feature request image: File a new feature request
  2. Describe your request
  3. Describe use-cases for this feature
  4. Include screencaps as applicable
  5. Include links to any related samples, issues, pull requests, or documentation

Adding to FAQ

In case you find a discussion that should be added to the FAQ, please let us know!

Leave a new comment on the FAQ, and we will add it to the main list.

Thanks for the help!

Supporting material

Web Chat

BotFramework SDK

Accessibility

Adaptive Cards

Speech

GitHub

@compulim
Copy link

compulim commented Jan 4, 2021 •
edited

.Net -> .NET
therfore -> therefore
Voiceover -> VoiceOver
DL Speech / DirectLine Speech -> Direct Line Speech
WebChat -> Web Chat

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment