Architecture: hbf-webchat

C4 Component Diagram

Key Flows

Widget initialisation (BUBBLE mode)

1. Host page calls HBFWebchat.init({ deploymentId, apiUrl }).
2. ext_libraries loader fetches botframework-webchat from CDN.
3. WebChatConfig.getBotPreferences() calls GET <apiUrl>/public/bot-deployments/<deploymentId> on hbf-core (up to 3 retries). The response is deep-merged with defaultBotProperties.
4. App() injects CSS custom properties from botPreferences.styleSetOptions via css-vars-ponyfill.
5. new BubbleWidget(...) is constructed. It finds or creates the host <div>, renders the floating button HTML, and optionally starts PreChatManager.
6. When the user first clicks the button, CoreWidget.setUpWebchat() fetches a Direct Line token from tokenURL, calls createDirectLine(token), registers all middlewares, and calls renderWebChat().
7. The webchat is now live. Subsequent messages flow over the Direct Line WebSocket to hbf-bot.

Activity received from bot

1. Direct Line delivers an activity to the botframework-webchat Redux store.
2. ActivityMiddlewares inspects activity.type and activity.channelData:
   • Regular bot messages: rendered by botframework-webchat's default pipeline.
   • Live-chat agent messages: wrapped in LiveChatMessageActivityDecorator.
   • CSAT trigger events: CsatManager shows the popup overlay.
   • Rating form trigger events: RatingFormManager shows the star rating overlay.
3. AttachmentMiddlewares intercepts adaptive card attachments and delegates to AdaptiveCardDecorator for custom rendering (version, host config overrides).
4. ActivityStatusMiddlewares renders reaction buttons and delivery status below each bot message.
5. NotificationManager may show a toast if the activity matches a startup notification rule.

Locale change

1. User selects a language from LocaleDropdown (rendered in the chat header).
2. CoreWidget.updateLocaleAndRender() is called with the new locale code.
3. LocaleManager loads the matching translation JSON from src/assets/translations/.
4. The botframework-webchat store locale is updated, causing a re-render with the new strings.
5. The locale is persisted in WebStorage for the next session.

Pre-chat steps (optional)

1. If botPreferences.widgetStyleSet.advancedChatPromptBubble.enable is true, BubbleWidget creates a PreChatManager instance before rendering the floating button.
2. PreChatManager renders a form collecting required user fields (name, email, etc.) inside the chat panel area.
3. On completion, PreChatManager.onComplete() calls BubbleWidget.onPreStepsComplete(), which calls setUpBubbleWebchat() and opens the Direct Line connection with the collected data passed as channel data on the greeting activity.

Speech (TTS / STT)

1. If botPreferences.azureSpeechTokenURL is set, CoreWidget.setUpWebchat() fetches an Azure speech token.
2. createSelectVoice() builds a botframework-directlinespeech-sdk speech factory scoped to the deployment's language.
3. The factory is passed as webSpeechPonyfillFactory to renderWebChat(), enabling the microphone button and bot TTS.