Webchat Implementation Guide

Scope

This guide documents how the current webchat implementation works in code, what is already production-usable, and what is still planned.

Current Architecture

Runtime components

• Public widget script: public/embed/replybase-webchat.js
• Public APIs: init, config, message, and events routes
• Session token utility: lib/webchat-session.ts
• Channel/session resolver: lib/webchat.ts
• CORS utility: lib/webchat-cors.ts
• AI pipeline integration: lib/ai-engine.ts

Data storage (current)

• WebChatSite: site identity and config
• WebChatSession: visitor-session continuity
• WebChatEvent: diagnostics and audit telemetry
• CRM continuity remains on channel/contact/conversation/message

Request Flows

1) Session Initialization

• Widget calls init with publicKey (preferred) or channelId/botId.
• Widget first calls config to obtain one-time init challenge.
• Server validates CORS, resolves site/channel, enforces domains.
• Server verifies and consumes challenge to block replay.
• Server creates or restores session and issues signed token.

2) Config Fetch

• Widget calls config with publicKey or channelId/botId.
• Server validates origin policy and allowed domains.
• Server returns safe config plus short-lived init challenge.

3) Message Send

• Widget calls message with session token and message body.
• Server verifies token, ownership, and source metadata.
• Flow-first execution, then AI fallback when needed.
• Server persists transcript and updates session continuity.
• Safe fallback copy is returned if engine fails.

4) Client Telemetry

• Widget calls events endpoint for lifecycle signals.
• Server validates token/site/origin and applies sampling.
• Sampled events are persisted and session lastSeen is touched.

Embed Runtime Features

• Shadow DOM isolation
• Unread launcher badge
• Mobile full-screen mode support
• Cookie-consent gating for init/storage
• Telemetry mode and event whitelist toggles

Dashboard Setup Flow

Path: /integrations/webchat

• bot selection and web channel creation/selection
• theme and widget configuration
• public/secret key reveal, copy, and rotation
• allowed domain management and diagnostics
• internal harness launch and live preview
• embed snippet generation and copy

Flow Builder + Webchat Playbook

1. Create a flow in /flows and add your step sequence.
2. Mark the flow active and assign as the bot entry flow.
3. Open /integrations/webchat and select the same bot/channel.
4. Configure branding, welcome copy, and allowed domains.
5. Save Config and run Launch Test Widget before site rollout.
6. Monitor blocked-origin and rate-limit diagnostics post-launch.

Feature Matrix

• Deterministic flow runtime: message, input, condition, action, end nodes
• Flow-session continuity with variable capture per visitor
• Flow-first response path with AI fallback when needed
• Origin + referer enforcement at global and site level
• Init challenge replay protection and signed session tokens
• Diagnostics stream for blocked-origin and rate-limit events

Test Harness Behavior

The Launch Test Widget action opens an internal harness page that loads the production embed script with your selected site key and visual config.

• If an allowlist exists, the dashboard origin must be included.
• Launch now auto-syncs the current dashboard origin to allowlist when needed.
• Site-level origin checks still apply in init/message/events routes.

Security Notes (Current)

• HMAC-signed session tokens with expiry
• strict Origin + Referer controls on webchat routes
• rate limiting across init, message, and events
• bot mitigation checks for suspicious traffic
• configurable PII retention sanitization