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 thecompany_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.tsadopts 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).
setUserInteractionnotifies 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.vuepicks bycompany.ai_calling.call_interface.design—'modern'→AIVoiceWidget.vue, elseAIVoiceWidgetClassic.vue(pre-redesign snapshot; don't evolve it). Modern addsconnect_messagesrotating headlines, provider-agnosticsetSpeakerMuted(), a type-instead mid-call chat mode, a ringing tone while connecting, and ~20 new i18n keys (en/sv/ar).ai-call-client-logevents ship client-side call diagnostics. - Speech-to-speech sessions (
services/directS2SCall.ts, interface ins2sSession.ts, Vapi/Daily invapiCall.ts): when ms-comm returns avoice-directanswer the browser talks straight to the vendor — OpenAI over WebRTC (webrtc-relay, no vendor secret in the browser), Gemini over ms-comm'sws-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/lamejsin a worker) and uploaded to ms-commPOST /voice-direct/recording. Usage reports (DirectS2SUsage) are reconciliation data only.DirectAudioDebugtraces Gemini web audio. See Voice Engine. - Agency pause mid-session: the widget now listens for
company-settings-updatedon 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_urlfromgetStartingPageUrl()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 onintent: 'other'; Nox admin-forced engage bypasses heuristic suppressors (cooldowns, 48h agent-connected window, URL rules) but not hard blockers —setAutoTriggerrefuses withtab_hidden | user_interacted | call_active. An accepted CALL trigger message becomes the ElevenLabsfirst_message(Ultravox gets it via system prompt); chat-trigger replies respect the pre-chat form (pendingAutoTriggerMessageparks the visitor reply until the form completes); messages render multi-line. Delivery receipts:ai-auto-trigger-deliveryreportsdisplayed/blocked_reasonontoAIAutoTriggerMessageModel→ admin broadcastvisitor-engage-result+ backendPOST /internal/engage-receipt;log-auto-triggerrecords client-side URL-rule triggers. - Multi-calendar booking: widget receives server-computed boolean
company.multi_calendar_enabled(thego_high_levelsubdoc is never sent to the widget). When on, booking step 1 is a calendar picker (cal.purpose); theget-available-slotssocket emit carriescalendar_idand the reply echoes it (so a slow default reply can't clobber a picked calendar); the pick reaches the backend book endpoint ascalendar_booking_meta.calendar_id. - GA4/GTM:
sendTrackEvent()postsknockknock:trackto the parent page, forwarded togtag/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()instores/widget.ts: ends any call in flight, then asks the host page to drop the iframe;block-useris listened for on all three sockets; runs once per page load. Session tracking andrecoded_session.jsrecording continue. - Agent takeover of a visitor call (
0a8e82f) —IncomingCallCallbacks.isOnVisitorCall()andEndCallOptions.replacedByAgentCall→ theend-callpayload carriesreplaced_by_agent_call: true;TakeoverOptions.replacesVisitorCallauto-joins the agent's room instead of answering "user on another call". ms-comm preservescall_statusand sends no missed-call email. CalendarBookingMeta.booking_typegains'jobber'(mapped fromcalendar_typecontainingjobber).- 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 stepv-ifchains 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
poweredByUrlcomputed: 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) — loadsGET /bot-flows/public/:company_idonly whencompany.bot_flow_enabled; runs the published flow client-side, reports each step to ms-commbot-flow-step, submits answers to the backend and/orpostMessages them to the exactallowed_origin. AI follow-up buttons come back as an[[options: …]]marker parsed byoptionsMarker.ts(regex tightenedce2058a). See Bot Flow Builder. - Readable button text —
utils/color.tsreadableTextOn()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.vuelinkifyTranscript()escapes the text first, then turnshttp(s)://URLs intotarget="_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 undercomponents/retro/with calls and booking inside it, skins viaretro_skin/retro_custom_colors, bubble launcher since9fb5a01. Loader sizing lives inbackend/public/widget.js(knockknock:viewport). See Widget Types. - Semble booking choices (
4f01e38,ae6daae) —SembleChoicePicker.vue(Location → Clinician → Appointment type) replaces the purpose list whenbookingType === 'semble';CalendarBookingMeta.booking_typegains'semble'; a choice with no slots setsnoSlotsForChoiceand clears the previous slots. See Semble. - AI sees human-agent replies —
stores/widget.tsnow pushes agent replies (and messages received while the chat is minimized) intoprevious_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 tokk_widget_type_launcher; when the company'slauncher_stylediffers 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) — backendGET /get-user-session/:idreturnsusersession.sales_suppressed: true(only when true) for a Won contact on a company whose Nox Funnelcustomers.modeisstop_selling(customers.skipCustomer, fails open; also forceslead_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/tokenis called with{ company_id, user_session_id }instead of a random identity; ms-comm mintsvisitor_<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 advertisesmedia_transport: 'livekit',directS2SCall.tsjoins 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=wson the host page forces the socket for side-by-side tests. See Voice Engine. - Parent-origin pinning (
97eea79) —postMessage.tsandheadlessBridge.tspin the host origin only from a message whoseevent.source === window.parentwith a real origin. Browser extensions posting into the frame (e.g. TronLink) used to pin their origin, soknockknock:widget_readywent nowhere and the loader kept the widget at opacity 0. - Deleted conversations (
4b2753c) — the always-on socket listener handles ms-commchat-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 skipsnullentries inchat.messages(9bec17e43). - Booking types —
CalendarBookingMeta.booking_typegainspracsuite(purpose picker shared with Semble,431c9c6) andservicem8(d5167ab). - Retro IM — the "has just signed in" toast was removed (
39648eb);store.retroToastis forced false for old builds.