Skip to main content

Voice Nox

Audience: Sales · Support · QA · Engineering · Management · Where in app: Nox window → Call / Talk to Nox; Nox Live → Talk to Nox · Plan availability: every company (AI credits per call)

Voice Nox lets an admin talk to Nox. Since the November 2026 launch the voice agent is a thin conversational layer: it handles speech and turn-taking, answers what its session brief already knows, and hands everything about the business to the v2 engine as a job. Customer-facing guide: docs-site → AI Features → Calls with Nox.

Stack​

  • ElevenLabs Conversational AI over WebRTC/WebSocket (@elevenlabs/client Conversation, frontend/src/composables/useKnoxVoice.js), with a signed URL from ms-ai POST /knox-voice/signed-url (@AiSpend('nox_voice')).
  • LLM: KNOX_VOICE_LLM — PROD claude-sonnet-5-5 (default KNOX_VOICE_DEFAULT_LLM in knox-voice/knox-voice.constants.ts, since f7e6a053e, 8 Nov). The earlier custom-llm (Z.ai GLM) value and its "never revert" rule are history.
  • The Grok/xAI and Gemini Live work in the same window (voice-direct, LiveKit, SIP) is for the AI phone agents, not Nox calls.
  • One shared ElevenLabs agent; per-session overrides (company context, white-label name, agency nox_voice_id, the call brief) are spliced in at signed-url time. KNOX_VOICE_AUTOSYNC re-syncs the agent's tools on boot; Admin → Knox → Voice Tools syncs on demand. Re-sync PROD after a voice-tool change (e.g. nox_call_me_back, f52e6005).
  • Sessions are capped at 20 minutes by ElevenLabs; the frontend reconnects and continues ("I'm back — the line hit its twenty-minute limit…", composables/noxCallContinuity.js). White-label calls never say the product name (acbdc543c).

Voice tools (one brain)​

Since 4bbd15677 the voice agent carries only v2's tools (knox-voice/knox-voice-v2-tools.ts); there is no map of data-read tools on the voice agent any more (a website-only lookup once answered "no leads" while a customer had emailed).

ToolPurpose
nox_delegateHand the admin's request, made self-contained (every name/email/phone/date said so far), to a v2 run. Also used to answer a job's question, change it (action: "change") or cancel it.
nox_confirmResolve a waiting card by voice (card handles C1, C2…).
nox_ui_highlightPoint at an element on the admin's shared screen (never clicks).
nox_call_me_backOne-job permission to speak up when the results are ready.

The standing voice rules (V2_VOICE_DELEGATE_LINES / V2_VOICE_RESULT_LINES) say: answer from the session brief only for account/setup, recent requests, page guides, can/can't-do and the screen; delegate everything else; never promise something on neither can/can't list (hand it over as a question).

Hand-overs and jobs​

  • Each delegated request becomes a knox_v2_runs row with request.dto.voice_call_id (the call's knox_conversation_id, not the ElevenLabs id), job_ref (J1, J2…) and optionally quick_only. Runs from a call bill to nox_voice:<callId> (wallet "Nox voice call").
  • Quick answers inside the hand-over: a plain question goes first as quick_only; if it returns within 3.5s the answer is spoken in the same turn, otherwise nothing ran and it becomes a normal job (store/knox.js; orchestrator quick_only, admin_words, 4-step researcher).
  • Job numbering continues across calls: context/jobs.service.ts lastJobNumber takes max(Jn) over the last 24h (JOBS_LOOKBACK_HOURS) and returns it as job_seq on the signed URL, so a reload or redial continues instead of restarting at J1.
  • Honest job times: GET /knox-v2/voice/job-estimates — p75 of call jobs (excluding quick tries) over 2 weeks, refreshed hourly (voice/nox-job-estimate.service.ts; mirrored in frontend/src/composables/noxJobEstimate.js — keep the two in step). A call-back is offered only for long work.
  • Delivery rules (frontend 91be3b79, 16 Nov): one short hand-over line, no time promised; a result the admin is waiting for is said at once; if they moved on it waits for a real pause (~4s) and is named by what they asked; team results wait until the admin's latest words are answered.

Job inbox​

The server decides how a call opens (context/inbox.ts, 704cfcb5f / frontend bae89e19). The signed-url response carries inbox_greeting, inbox_context, inbox_jobs / inbox_tells: results the admin is owed, failed jobs, and questions a job is still waiting on. The call opens with the inbox's first line word for word; one spoken reply can answer all of a job's open asks (POST /knox-v2/runs/:id/input with all). POST /knox-v2/voice/inbox/told marks inbox results as said (knox_v2_runs.told_at). This is distinct from the panel's Inbox (conversation threads + Waiting for you).

Server-written call reports​

Behind the platform switch nox_voice_server_reports (Admin → Settings → Feature Flags → "Server-written call reports"; replaced NOX_VOICE_SERVER_REPORTS; read per call, so it takes effect on the next call). When on, ms-ai writes a call's job reports — progress notes (first at 10s, then every 25s, hand-off line at 90s, 8s after the admin speaks), the result, and failures (voice/call-reports.ts) — publishes them on Redis knox_voice_events:<callId>, and queues them per call (2h TTL) until the browser acks (voice/nox-call-relay.service.ts). Endpoints: POST /knox-v2/voice/calls/:callId/heard (admin just spoke), GET …/reports, POST …/reports/ack. When off, the browser writes the reports itself. The signed URL tells the frontend which mode is on (server_reports).

After the call​

  • POST /knox-v2/voice/call-ended sends open_run_ids, untold_run_ids, call_back_run_ids, nox_name.
  • After-call answers (voice/after-call.ts, voice/nox-after-call.service.ts): a job still running at hang-up has its result sent once through the contact policy — push, the inbox during quiet hours, or email if nothing reached the admin live. Results that arrived but were never said go out right away.
  • "Working on it" list (components/knox/NoxWorkingList.vue): shown for long jobs (or > 15s), last 30 min, 90s after everything finishes; Call me when ready / Turn off.

Call-backs​

nox_call_me_back (or Call me when ready) marks runs call_back. With the page open the frontend rings itself (a Ready note, composables/noxCallBack.js) and acks POST /knox-v2/voice/call-back/ack. Otherwise voice/nox-call-back.sweep.ts (every 30s + 5s after boot, Redis lock nox_call_back_sweep_lock, off with NOX_CALL_BACK_SWEEP=off) sends one nox-callback push once every booked run has settled: 20s grace for the live app, 5-min lease, 24h max age, 60-min stuck-job cutoff, quiet 21:00–08:00 local. Migration 1794700000000-knox-run-call-back-open-index. Backend (e5ed166bb): nox-callback is a tier-1 notification with its own quiet window, title "<name> is calling you back", APNs category NOX_CALLBACK (interruption level active, FcmService.js), route nox_callback; time zone falls back user → company → Pacific/Auckland (lib/adminTimezone.js). call-back/ack is for the mobile app.

After-call rating​

composables/noxCallRating.js: "How was that call?" 👍 Good / 👎 Not great (+ reason: Didn't understand me, Wrong answer, Too slow, Talked too much, Skip), at most once a day, only after calls ≥ 30s and within 4.5 min (ElevenLabs accepts ratings for 5). Posted to POST /knox-voice/feedback/:knoxConversationId; graded alongside chats by the daily quality check.

Screen sharing​

Consent is per admin, server-side (knox_v2_screen_consent; GET /knox-v2/screen/consent, POST …/grant|revoke; card "May I look at your screen when it helps?"). With consent, a run requests a snapshot (POST /knox-v2/runs/:id/screen) and the server rebuilds it field by field, never trusting the client's shape (run/knox-v2-screen-access.service.ts). The browser sends a text description, never pixels; password/API-key/card/OTP fields are never read and secret-looking values are masked (composables/useScreenSnapshot.js, 92699137). The Share screen button pulses when Nox asks for it (7f438a54).

Greetings and waking up​

  • Greeting mic — nox_rapport.style.greet_listen (default false, backend/app/lib/noxRapport.js): when on, a greeting Nox starts by itself listens for the answer without a tap.
  • Wake mode — quiet (default) / speak / off, with agency override and lock — see v2 engine.
  • The upgrade intro and the morning greeting are wake moments: the greeting waits while Nox is busy instead of giving up for the day (4ab0addf).

Endpoints​

  • ms-ai knox-voice: POST signed-url, POST playground/signed-url, POST tools/:toolName, POST feedback/:knoxConversationId, POST events/:knoxConversationId, GET calls/:threadId[/audio], POST lines-busy, POST admin/sync. During-call display events fan out over Redis pub/sub (knox-voice-events.service.ts) because the tool webhook and the browser's SSE land on different pods.
  • ms-ai knox-v2: voice/call-ended, voice/call-back/ack, voice/job-estimates, voice/calls/:callId/{heard,reports,reports/ack}, voice/inbox/told, runs/:id/{input,screen}, screen/consent*.
  • Transcripts persist to knox_call_transcripts (ms-ai) — see Visitor data; super admins browse calls (summary + recording) in Admin → Knox → Conversations.

Env vars (ms-ai)​

ELEVENLABS_API_KEY, KNOX_VOICE_LLM, KNOX_VOICE_DEFAULT_VOICE_ID, KNOX_VOICE_AUTOSYNC, KNOX_V2_DEFAULT, NOX_CALL_BACK_SWEEP, SECRET_AUTH_TOKEN, BACKEND_BASE_URL, AI_BASE_URL, ANTHROPIC_API_KEY.