Skip to main content

widget — Embeddable Visitor Widget

The lightweight Vue 3 app that customers install on their sites. It launches chat/calls and talks to the AI agents. Session recording runs in the host page (recoded_session.js), not in this iframe — the widget host element is blocked from recordings.

  • Stack: Vue 3 + TS + Vite, Pinia, axios, socket.io-client (bundled), livekit-client 2.16.1, vue-tel-input, ElevenLabs client, Twilio Video. Deliberately lean (no heavy dashboard deps).
  • Output: a static SPA/iframe bundle, served by nginx (Docker) and fetched fresh by customer sites — no auto-updater (unlike desktop).

Embedding​

A loader snippet on the customer page mounts the widget in an iframe (#app). Install methods (script tag, GTM, WordPress, Shopify) are covered in the customer docs; internally the key points are:

  • The widget holds a persisted user_session_id (localStorage UUID, survives refreshes) and the company_id.
  • It communicates with the host page via postMessage (services/postMessage.ts) — resize, user-interaction signals (to suppress auto-trigger), and the page summary used for page rules.
  • Agent K landing: stores/widget.ts adopts a session id from a /k/<id> path (survives GHL redirects) or ?knock_id= param, so an Agent K click continues the known lead's session.
  • Consent gating lives in the host-page loader (backend/public/widget.js), not this repo — see Consent Gating.

Headless SDK​

backend/public/kk-sdk.js (window.KnockKnockSDK) embeds the widget iframe with &headless=1 — AI chat + AI voice only, no widget UI/video/human escalation. Bridge: src/services/headlessBridge.ts; postMessage protocol prefixed knockknock:sdk_ — commands sdk_chat_send, sdk_voice_start/end/mute; events sdk_ready, sdk_ack, sdk_error, sdk_chat_message/typing/seen, sdk_voice_status/transcript/level/mute_state; sdk_ready also carries agents + features.agents. requestCall() and /ai-outbound/sdk-trigger were removed (c91e6b1f0).

voice.start({ agent?, instructions?, greeting? }) — agent is the key of a dashboard SDK voice agent (company.sdk_voice_agents, CRUD /sdk-voice-agents in backend SdkVoiceAgentController, cap sdk_voice_agents_allowed, default 0, set by super admin via PUT /company/:_id/sdk-voice-agents-allowed). Its greeting, instructions and AI engine settings (model, voice, language, speech settings, memory; blank = the Widget Voice Agent's) are applied server-side; the page only ever sees { agent_key, name, category, greeting } via voice.agents(). Inline instructions / greeting are always allowed and ignored when agent is given. Errors: voice_busy (one call at a time — voice.end() resolves once idle), agent_not_found, agents_unavailable, mic_denied, voice_unavailable. The public docs page (frontend/src/views/sdk-docs/sdkReference.js) carries a carousel example; backend/public/tech.html is the demo deck.

Structure (src/)​

main.ts create app, init Pinia. No rrweb recorder since ff382f6
(the parent page blocks the widget in its recording)
stores/widget.ts the main store — most widget state & lifecycle, page rules,
auto-triggers, Agent K session adoption, spoken-link extraction
services/
api.ts fetch-based HTTP client
socket.ts Socket.IO connections (backend, ms-communication; the
ms-sessions socket is no longer opened — it had no consumer).
socket.io-client is an npm dependency, dynamically imported
into its own chunk — no jsDelivr fetch since b12b2fa
call.ts Twilio video call setup & permissions
aiCall.ts AI voice call; @elevenlabs/client + Ultravox dynamically
imported at call start
headlessBridge.ts headless-SDK postMessage bridge
postMessage.ts parent-window IPC
sound.ts ringtones/notifications
components/ Widget (launcher), ChatWidget, IncomingCallScreen,
AICallTakeoverScreen, ProductSlider
components/widgets/ launcher variants + AIVoiceWidgetSwitch → AIVoiceWidget
(modern) / AIVoiceWidgetClassic (frozen snapshot)
composables/ useChatLogic, useI18n
utils/sanitizeMessageHtml.ts chat HTML sanitizer (see below)
i18n/messages.ts single-file locales — en | sv | ar (RTL via [dir='rtl'] CSS)

What it captures & sends​

  • Session recording: none from the iframe (ff382f6). setUserInteraction notifies the parent (widget_interaction) only for visitor-led opens (track !== false) — the parent uses it to keep the session across pages in GDPR safe mode, so restored/agent-forced opens must not send it.
  • Sockets (keyed by company_id + user_session_id):
    • backend — company config, session lifecycle.
    • ms-communication — chat messages, AI chat streaming, chatbot flow, and server-pushed Nox auto-engage (nox-auto-engage-message).
  • REST: /companies/{id}, /files/{id}/get, /user-session/{id}/, calculate-lead-auto-connect-message.
  • Events: open/close, call start/end, chat expand, user-interaction, permission prompts.

Call & chat UX​

  • Video: Twilio Video (WebRTC) with mute toggles.
  • Voice UI designs: components/widgets/AIVoiceWidgetSwitch.vue picks by company.ai_calling.call_interface.design — 'modern' → AIVoiceWidget.vue, else AIVoiceWidgetClassic.vue (pre-redesign snapshot; don't evolve it). Modern adds connect_messages rotating headlines, provider-agnostic setSpeakerMuted(), a type-instead mid-call chat mode, a ringing tone while connecting, and ~20 new i18n keys (en/sv/ar). ai-call-client-log events ship client-side call diagnostics.
  • Speech-to-speech sessions (services/directS2SCall.ts, interface in s2sSession.ts, Vapi/Daily in vapiCall.ts): when ms-comm returns a voice-direct answer the browser talks straight to the vendor — OpenAI over WebRTC (webrtc-relay, no vendor secret in the browser), Gemini over ms-comm's ws-relay (mic chunks sized to Google's Live API guidance), xAI over websocket. Mic with echo-cancel/NS/AGC; agent audio only via an <audio> element; playout jitter buffer 150 ms (was 50 ms). OpenAI web calls are recorded in the browser (services/recording/callRecorder.ts, MP3 via @breezystack/lamejs in a worker) and uploaded to ms-comm POST /voice-direct/recording. Usage reports (DirectS2SUsage) are reconciliation data only. DirectAudioDebug traces Gemini web audio. See Voice Engine.
  • Agency pause mid-session: the widget now listens for company-settings-updated on the company room and re-fetches /company/:id (jittered up to 4 s, overlapping events collapsed), so a pause takes hold without a page reload.
  • AI voice: ElevenLabs realtime — streaming transcripts, frequency visualization, one/two-way modes, AI-call takeover screen, agent language auto-switch (language_detection). Spoken-link extraction (stores/widget.ts): phonetic URL reconstruction from transcripts ("dot"/"slash" tokens), TLD allowlist for bare hosts, "at"-preceded hosts treated as emails not URLs, links auto-dismiss after 10s (VOICE_CALL_LINKS_TTL_MS).
  • Chat: Socket.IO message stream supporting human agents, an AI chatbot (multi-turn flow with options/products/booking), and hybrid escalation (AI → human queue with a ~3-min fallback). Phone inputs use vue-tel-input (E.164) in pre-chat/chat/voice screens.
  • Chat sanitization: src/utils/sanitizeMessageHtml.ts — allow-list of formatting tags, all attributes stripped except safe hrefs; disallowed tags are escaped (rendered visibly), not removed; FIFO memo (400 entries).
  • Chat page attribution: message and reset-chat emits carry page_url from getStartingPageUrl() so transcripts know the chat's starting URL.
  • Auto-triggers: ai_auto_trigger.allow_second_message (default true) lets the auto-connect agent send a follow-up on intent: 'other'; Nox admin-forced engage bypasses heuristic suppressors (cooldowns, 48h agent-connected window, URL rules) but not hard blockers — setAutoTrigger refuses with tab_hidden | user_interacted | call_active. An accepted CALL trigger message becomes the ElevenLabs first_message (Ultravox gets it via system prompt); chat-trigger replies respect the pre-chat form (pendingAutoTriggerMessage parks the visitor reply until the form completes); messages render multi-line. Delivery receipts: ai-auto-trigger-delivery reports displayed/blocked_reason onto AIAutoTriggerMessageModel → admin broadcast visitor-engage-result + backend POST /internal/engage-receipt; log-auto-trigger records client-side URL-rule triggers.
  • Multi-calendar booking: widget receives server-computed boolean company.multi_calendar_enabled (the go_high_level subdoc is never sent to the widget). When on, booking step 1 is a calendar picker (cal.purpose); the get-available-slots socket emit carries calendar_id and the reply echoes it (so a slow default reply can't clobber a picked calendar); the pick reaches the backend book endpoint as calendar_booking_meta.calendar_id.
  • GA4/GTM: sendTrackEvent() posts knockknock:track to the parent page, forwarded to gtag/dataLayer; legacy event names kept (KnockKnock_open_chat, KnockKnock_open_chatbot). openChat({track:false}) for programmatic (non-visitor) opens.
  • Products/booking: inline product cards (Shopify/custom) and calendar booking (Calendly/Google/GHL/HubSpot/Jobber/Semble) during chat or AI call. Launcher style is now resolved per-device (mobile_launcher_style).

Versioning & deployment​

npm run version:bump (--minor/--major) bumps package.json. npm run build type-checks and produces the dist/ bundle. Multi-stage Docker (Node 22 builder → nginx Alpine) pushed to ECR via buildspec.yml. Customers always pull the latest bundle from the CDN/domain.

2026-08/09 changes​

  • Blocked visitors — one applyBlocked() in stores/widget.ts: ends any call in flight, then asks the host page to drop the iframe; block-user is listened for on all three sockets; runs once per page load. Session tracking and recoded_session.js recording continue.
  • Agent takeover of a visitor call (0a8e82f) — IncomingCallCallbacks.isOnVisitorCall() and EndCallOptions.replacedByAgentCall → the end-call payload carries replaced_by_agent_call: true; TakeoverOptions.replacesVisitorCall auto-joins the agent's room instead of answering "user on another call". ms-comm preserves call_status and sends no missed-call email.
  • CalendarBookingMeta.booking_type gains 'jobber' (mapped from calendar_type containing jobber).
  • Audio: ScriptProcessor buffer is rate-dependent — sampleRate > 24000 ? 8192 : 4096 — so chunk duration stays ~170–186 ms at 44.1/48k (aiCall.ts).
  • Reschedule panel (66e095c): the step v-if chains were merged (step 0 rendered two panels; Confirm submitted with no date), the intent regex covers "re schedule"/"rebook"/bare "reschedule", and Google's 'primary' is no longer passed as a calendar override.
  • Powered by is one poweredByUrl computed: whitelabel override URL → affiliate link → knockknockapp.ai, only for direct (non-agency) companies with the override off; override-on-with-empty-URL removes the link.
  • Served scripts are obfuscated + white-labelled — see Widget installation.

2026-10 changes​

  • Bot Flow runtime (services/botFlow/, 9f44788) — loads GET /bot-flows/public/:company_id only when company.bot_flow_enabled; runs the published flow client-side, reports each step to ms-comm bot-flow-step, submits answers to the backend and/or postMessages them to the exact allowed_origin. AI follow-up buttons come back as an [[options: …]] marker parsed by optionsMarker.ts (regex tightened ce2058a). See Bot Flow Builder.
  • Readable button text — utils/color.ts readableTextOn() is the text/icon fallback on every launcher when only a background colour is set (Styles & Appearance).
  • Welcome close button uses welcome_widget_colors.close_btn_color / close_btn_icon, falling back to the chat button colour + white.
  • Voice transcript links (61b9684) — AIVoiceWidgetClassic.vue linkifyTranscript() escapes the text first, then turns http(s):// URLs into target="_blank" rel="noopener noreferrer" links (trailing punctuation excluded); long URLs wrap (overflow-wrap: anywhere) in both voice designs.
  • Retro IM launcher style (eb102a0, a3b8ca7, 9fb5a01) — launcher_style: 'retro', a 2003-messenger window under components/retro/ with calls and booking inside it, skins via retro_skin / retro_custom_colors, bubble launcher since 9fb5a01. Loader sizing lives in backend/public/widget.js (knockknock:viewport). See Widget Types.
  • Semble booking choices (4f01e38, ae6daae) — SembleChoicePicker.vue (Location → Clinician → Appointment type) replaces the purpose list when bookingType === 'semble'; CalendarBookingMeta.booking_type gains 'semble'; a choice with no slots sets noSlotsForChoice and clears the previous slots. See Semble.
  • AI sees human-agent replies — stores/widget.ts now pushes agent replies (and messages received while the chat is minimized) into previous_messages, so after a human agent answers, the AI's next reply takes it into account.

2026-11 changes​

  • Launcher style wins over a saved widget type (060b966) — kk_widget_type (written on minimize/expand) is now tied to kk_widget_type_launcher; when the company's launcher_style differs from the one it was saved under, the saved type is dropped and the new style renders. Visitors with a pre-fix value reset once.
  • No sales pop-ups for customers (f4c89aa) — backend GET /get-user-session/:id returns usersession.sales_suppressed: true (only when true) for a Won contact on a company whose Nox Funnel customers.mode is stop_selling (customers.skipCustomer, fails open; also forces lead_auto_connect_threshold_reached: false). canShowAutoTrigger() then returns false: no lead-score, page-rule or default-message pop-ups. Chat still works when opened.
  • Twilio call token bound to the visitor session (5711ddd) — /twilio/token is called with { company_id, user_session_id } instead of a random identity; ms-comm mints visitor_<user_session_id> only for a session of that company. See Telephony › Carrier webhook & token auth.
  • Web Gemini over LiveKit (bd354a2) — when ms-comm's voice-direct setup advertises media_transport: 'livekit', directS2SCall.ts joins ms-comm's LiveKit room (voice-direct-livekit-join → { url, token }; mic and agent as tracks, relay events on the data channel) instead of the web-media socket. ?vd_transport=ws on the host page forces the socket for side-by-side tests. See Voice Engine.
  • Parent-origin pinning (97eea79) — postMessage.ts and headlessBridge.ts pin the host origin only from a message whose event.source === window.parent with a real origin. Browser extensions posting into the frame (e.g. TronLink) used to pin their origin, so knockknock:widget_ready went nowhere and the loader kept the widget at opacity 0.
  • Deleted conversations (4b2753c) — the always-on socket listener handles ms-comm chat-deleted (and a 410 from the chat fetch) by dropping local chat state and stored AI context, like "New chat" without telling the server. Backend's widget chat fetch also skips null entries in chat.messages (9bec17e43).
  • Booking types — CalendarBookingMeta.booking_type gains pracsuite (purpose picker shared with Semble, 431c9c6) and servicem8 (d5167ab).
  • Retro IM — the "has just signed in" toast was removed (39648eb); store.retroToast is forced false for old builds.