Events & errors

onAction

// All five types are exported from @voqal/usher-core.type AgentAction =  | { kind: "navigated"; destinationId: string; path: string; reason: string; kbAnswer?: KbAnswer }  | { kind: "offer"; destinationId: string; title: string; reason: string; kbAnswer?: KbAnswer }  | { kind: "clarify"; question: string; reason: string }  | { kind: "answer"; reason: string; text?: string; kbAnswer?: KbAnswer }  | { kind: "tool"; name: string; status: ToolRunStatus; durationMs: number; response: Record<string, unknown> }  | { kind: "refused"; reason: RefusalReason; detail: string; fallback?: NavTarget; destinationId?: string };type ToolRunStatus = "ok" | "invalid_args" | "declined" | "error" | "timeout" | "not_run";interface KbAnswer {  text: string;  citations: { sourceId: string; title: string }[];}type RefusalReason =  | "no_matching_destination" // live: no page this user can reach matches the request  | "not_requested" // live: a navigation on a message that asked for nothing ("hi", "ok")  | "already_here" // the page the user is already on; destinationId names it  | "needs_destination" // live: "take me somewhere" without saying where  | "repeat_offer" // live: the same page offered twice for one message  | "tool_loop" // live: too many tool calls for one message  | "unknown_tool" // live: the model called a tool that doesn't exist  | "not_in_allowlist"  | "role_forbidden"  | "param_unresolved"  | "low_confidence"  | "unsafe_target"  | "navigation_failed";interface NavTarget {  destinationId: string;  path: string; // the concrete path, params filled in}

import type { AgentAction } from "@voqal/usher-core";function handleUsherAction(action: AgentAction) {  switch (action.kind) {    case "navigated":      analytics.track("usher_navigated", { destination: action.destinationId, path: action.path });      break;    case "offer":      analytics.track("usher_offered", { destination: action.destinationId });      break;    case "clarify":    case "answer":      break;    case "refused":      analytics.track("usher_refused", { reason: action.reason });      break;  }}<Usher voqalKey={import.meta.env.VITE_VOQAL_KEY} router={adapter} destinations={destinations} onAction={handleUsherAction} />

• In a live session, onAction fires for each tool call the model makes: navigate → navigated (or a refusal), offer_navigation → offer, clarify → clarify, and decline_navigation → refused with no_matching_destination. A navigation attempted on a message that asked for nothing (“hi”, “👍”, “ok”) is not run and arrives as refused with not_requested. A navigation or offer for the page the user is on arrives as refused with already_here. A plain spoken reply with no tool call fires nothing. The words themselves are in the chat panel, not in the action.
• Tapping a suggestion card fires one more action with the navigation result, usually navigated, in live sessions and in local mode alike. “No thanks” fires nothing.
• Treat reason and detail as developer text. Don’t show them to users, and don’t branch on their wording.

Refusals

A refusal means nothing moved. In a live session the assistant explains it in its own words. In local mode the panel shows the fixed line below. detail can quote what the user asked for, so treat it as user content in your analytics.

fallback appears on param_unresolved when the destination has a parent without params. Usher doesn’t follow it on its own. In local text mode the panel shows a suggestion card for the parent page, without “No thanks”. To follow it automatically instead:

// Take the user to the list page when Usher couldn't tell which record they meant.function handleUsherAction(action: AgentAction) {  if (action.kind === "refused" && action.reason === "param_unresolved" && action.fallback) {    void router.navigate(action.fallback.path); // e.g. "/cases"  }}

Voice errors

voice.onError gets anything that stops a session from starting or keeps it from running. With a key and no other voice options, pass just voice={{ onError }}. Each time, the orb goes back to rest. Usher also logs start failures with console.error("[usher] startVoice failed:", error).

Hosted-key errors

With a voqalKey, a session that can’t start because of the key arrives as UsherCloudError, with the HTTP status (0 for a network failure) and a code:

import { UsherCloudError } from "@voqal/usher-core";import {  LiveSessionNotConnectedError,  Usher,  UsherSessionLostError,  type UsherVoiceConfig,} from "@voqal/usher-react";const voice: UsherVoiceConfig = {  onError: (error) => {    if (error instanceof UsherSessionLostError) {      toast("The assistant disconnected. Tap the orb to reconnect.");      return;    }    if (error instanceof LiveSessionNotConnectedError) {      toast("That message didn't send. Try again in a moment.");      return;    }    if (error instanceof UsherCloudError && error.code === "rate_limited") {      toast("The assistant is busy. Try again in a minute.");      return;    }    if (error instanceof DOMException && error.name === "NotAllowedError") {      toast("Allow microphone access to talk to the assistant, or tap Aa to type.");      return;    }    reportError(error); // origin_not_allowed, grant_unavailable, socket errors, …  },};<Usher voqalKey={import.meta.env.VITE_VOQAL_KEY} router={adapter} destinations={destinations} voice={voice} />

A connect cancelled with × is not an error. VoiceSessionSupersededError is swallowed and reported only as the start-voice:cancelled diagnostic.

Logging errors

With a key, conversation logging runs in the background and never interrupts the user. Its failures go to cloud.onLogError, not to voice.onError. By default Usher prints one console warning. The calls involved are POST {base}/v1/sessions/{sessionId}/events for turns, and POST {base}/v1/sessions/{sessionId}/audio followed by a PUT to Voqal’s upload host for each audio clip. Codes you may see there, as UsherCloudError: session_quota_exceeded (429, the session hit 500 turns or 200 clips), session_expired (410, the session is over 2 hours old), and audio_exists (409, a clip was already uploaded). None of them affect the conversation.

Diagnostic events

voice.onDiagnostic(event, detail) reports the session lifecycle. Use it while you integrate, and turn it off in production. The detail values are for debugging and can change between releases.

The reliability events (turn:silent, turn:empty, turn:tool-loop, fallback:shown, reconnect:resumed) and the voice events (voice:on, voice:off, playback:start, playback:stop) are also sent in support diagnostics, and Voqal’s trace findings name them when you share a trace id.

More help: Troubleshooting.

Support & diagnostics

Every page load gets a trace id. Usher prints it once in the browser console:

[usher] trace tr_xxxxxxxxxxxxxxxx — share with Voqal support if something goes wrong

It’s also on ref.current.traceId, and getUsherTraceId() from @voqal/usher-react returns it anywhere, for example to attach to your own error reports. When you contact support, include it: it lets us find exactly what happened in that page load.

To diagnose problems, the SDK sends Voqal structured diagnostics, kept for 30 days:

• Setup: SDK and React versions, the adapter kind, destination counts, route patterns, alias count, role names from your roleScopes, knowledge entry count and size, instructions length, theme, interaction mode, and logging options.
• Browser: the user agent, the browser locale, whether the page is a secure context, and the page as your origin plus the matching route pattern (never the concrete path).
• Discovery: routes missing from your map, manifest overrides, duplicate ids or patterns, and invalid entries.
• Environment: microphone and AudioWorklet support, requests blocked by your Content Security Policy, a denied, dismissed, missing, or silent microphone, and a missing or malformed key.
• Sessions: start latency and failures (with codes such as origin_not_allowed), reconnects, and how each session ended.
• Turns: reply latency, what each tool call became, and the reliability events below.
• Errors: the error class, a redacted message, and the SDK's own stack frames.

Diagnostics never contain anything a user said or typed, your instructions or knowledge base text, context values such as selected record ids and labels or user ids, concrete page paths or URL query strings, or tokens, or more than a key's first four characters. They do contain the browser’s user agent and locale. They’re separate from conversation logs. They’re on by default with a key. Without a valid key, only setup, discovery, environment, key, and session-start failures are sent, never sessions or turns, since a missing key is a common reason a setup doesn’t work. Turn them off with cloud={{ diagnostics: false }}, though support can then see much less.