Skip to main content

Gotchas: hbf-webchat

Package-specific non-obvious patterns and pitfalls. Loaded on demand when working on this package.

  • Needs local/config.js for dev startup: The dev startup script imports ../local/config.js with no fallback. Must create the file manually with { deploymentId, apiUrl } before starting. The local/ directory is gitignored.

DirectLine Architecture​

  • hbf-webchat connects to hbf-bot via Microsoft's botframework-directline (Azure DirectLine), NOT open-bot-framework. The directline client is bundled inside botframework-webchat. OBF is a planned future self-hosted replacement but is not yet integrated.

Pre-Auth Token Init​

  • customData.authToken is extracted during invokeCustomFunctions(): Site owners pass authToken (and optional authRefreshToken) in HBF_retrieveUserInfo()'s customData. Extracted at CONNECT_FULFILLED (init) and on each message cycle. authIsPreAuth is set to true so the shield icon is non-clickable. Also supports runtime updates via HBFWebchat.setAuthToken(divId, token, refreshToken?).

Auth Status​

  • Webchat does NOT persist auth status in web storage: The shield icon only appears when the bot explicitly sends auth/status { authenticated: true }. Security is enforced server-side.
  • Auth/logout handled via AuthEventStep lifecycle step: Intercepts auth/logout events, clears auth store, sends auth/status { authenticated: false }, stops lifecycle. AuthEventStep is logout-only. Do NOT add auth/status re-emission there (race on session restart).
  • Auth/status re-emission belongs in auth nodes, not pipeline: authenticateUser and isAuthenticatedAction fire-and-forget sendAuthStatusEvent(). Ensures icon only appears when flow's auth check confirms validity.

CSS Variables and Widget Modes​

  • --headerBorderRadius, --headerMargin, --headerHeight are only set in the BUBBLE path of app.ts — not in EMBEDDED. Any feature that reads these variables (e.g., a listening overlay that needs to position itself below the header) must handle the undefined/unset case or provide CSS fallbacks (e.g., var(--headerHeight, 0px)).

  • .embed-widget-container needs position: relative for absolutely-positioned children to have a correct positioning context. Without it, absolutely-positioned elements (e.g., a listening overlay) will escape the container and position relative to the nearest positioned ancestor in the host page.