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/clientConversation,frontend/src/composables/useKnoxVoice.js), with a signed URL from ms-aiPOST /knox-voice/signed-url(@AiSpend('nox_voice')). - LLM:
KNOX_VOICE_LLM— PRODclaude-sonnet-5-5(defaultKNOX_VOICE_DEFAULT_LLMinknox-voice/knox-voice.constants.ts, sincef7e6a053e, 8 Nov). The earliercustom-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_AUTOSYNCre-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).
| Tool | Purpose |
|---|---|
nox_delegate | Hand 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_confirm | Resolve a waiting card by voice (card handles C1, C2…). |
nox_ui_highlight | Point at an element on the admin's shared screen (never clicks). |
nox_call_me_back | One-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_runsrow withrequest.dto.voice_call_id(the call'sknox_conversation_id, not the ElevenLabs id),job_ref(J1,J2…) and optionallyquick_only. Runs from a call bill tonox_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; orchestratorquick_only,admin_words, 4-step researcher). - Job numbering continues across calls:
context/jobs.service.tslastJobNumbertakes max(Jn) over the last 24h (JOBS_LOOKBACK_HOURS) and returns it asjob_seqon 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 infrontend/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-endedsendsopen_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.