Configuration & theming

<Usher> props

cloud options

Used only with voqalKey. Logging runs in the background, in batches, and never delays a reply.

// Keep transcripts, but don't upload audio.<Usher  voqalKey="pk_live_…"  router={adapter}  destinations={DESTINATIONS}  cloud={{ captureAudio: false, onLogError: (error) => console.warn("Usher logging failed", error) }}/>// Log nothing at all.<Usher voqalKey="pk_live_…" router={adapter} destinations={DESTINATIONS} cloud={{ logConversation: false }} />

When prop changes apply

<Usher> keeps one conversation per assistantId across remounts and route changes. Other props can change at any time:

• context, onAction, and theme apply on the next render.
• router, destinations, knowledge, resolveEntity, and reasoner apply to text turns at once. An open live session keeps the destinations and knowledge it started with, and the next session picks up the change. A live tool call is still checked against the new map.
• voice, voqalKey, and cloud are read when the next session starts.

Safe context

Context is a short list of labels you choose to share. It is never read from the page: Usher doesn’t read form fields, hidden inputs, or page text. The current route is added for you on every turn.

const context = useMemo(  () => ({ role: user.role, organizationId: user.orgId }),  [user.role, user.orgId],);<Usher voqalKey="pk_live_…" router={adapter} destinations={DESTINATIONS} context={context} />

On sign-out, await ref.current.runtime().logout(). It ends any live session, closes and clears the chat panel, and drops the stored conversation and context, so the next user starts clean. Changing organizationId does the same for the live session, so a conversation never carries over to another organization.

Knowledge base

A small list of answers that lives in your code. In a live session the model reads the entries directly (see below). In local text mode and on ref.sendText, Usher matches the question against each entry’s title, content, and trigger phrases, with light stemming and stop words removed. There an entry is used when it covers at least 30% of the question’s words, up to three entries are considered, and each one used is cited.

import type { KnowledgeEntry } from "@voqal/usher-core";export const KNOWLEDGE: KnowledgeEntry[] = [  {    id: "kb-consult-price",    title: "Consultation pricing",    content: "A first 20-minute consultation is free. Follow-up calls are billed at the lawyer's hourly rate.",    triggerPhrases: ["how much is a consult", "is it free", "consultation cost"],    destinationId: "consultations.book", // answer AND offer the booking page    source: "Help Center — Consultations", // shown as the citation  },  {    id: "kb-refunds",    title: "Refund policy",    content: "Refunds are available within 14 days of a charge. Contact support to request one.",    triggerPhrases: ["refund", "money back"],  },];<Usher voqalKey="pk_live_…" router={adapter} destinations={DESTINATIONS} knowledge={KNOWLEDGE} />

How answers combine with pages (local text mode)

• A plain answer or a navigation gets the knowledge answer attached.
• An offer for the page the entry links to becomes answer and offer.
• An offer for a different page becomes an answer only, because the knowledge base already answered it.

In a live session

• When a live session starts, Usher adds your entries to the model’s instructions as reference facts, in the order you list them. Voice and live chat can both answer from them.
• The section is capped at 8,000 characters (about 2,000 tokens) and only whole entries are included. Entries that don’t fit are left out, and Usher logs a console.warn saying how many. Put the entries that matter most first.
• The model answers with the fact first. If the entry names a page, it may offer the page after the answer, never instead of it, and only pages this user’s role can reach.
• Entries are facts, not instructions. Text in an entry can’t widen what the assistant is allowed to do.

Theme

Orb finish

• "aurora" (default): cyan to lavender glass.
• "iridescent": a slow hue drift, so it looks alive at rest.
• "midnight": made for dark surfaces, with a hot cyan core.
• A custom FinishTokens object: background (a CSS background shorthand), shadow (a box-shadow stack), ringRgb (the glow ring as "r, g, b"), and an optional animation shorthand.

<Usher  voqalKey="pk_live_…"  router={adapter}  destinations={DESTINATIONS}  theme={{ finish: "midnight", mode: "dark" }}/>

import { Usher, type FinishTokens, type UsherTheme } from "@voqal/usher-react";const BRAND_FINISH: FinishTokens = {  background:    "radial-gradient(ellipse 45% 35% at 33% 20%, rgba(255,255,255,.9) 0%, rgba(255,255,255,0) 62%)," +    "linear-gradient(160deg, #ffb36b, #e0457b)",  shadow: "inset 0 -10px 24px rgba(255,255,255,.35), 0 18px 44px rgba(224,69,123,.45)",  ringRgb: "224, 69, 123", // the glow ring, as "r, g, b"};const theme: UsherTheme = { finish: BRAND_FINISH, mode: "auto" };<Usher voqalKey="pk_live_…" router={adapter} destinations={DESTINATIONS} theme={theme} />

The finish also paints the small orb in the chat header and the assistant avatars. An unknown finish name falls back to aurora. The built-in tokens are exported as ORB_FINISHES if you want to start from one.

Mode

mode skins the chat panel and the orb’s corner controls. "auto" (default) follows the visitor’s prefers-color-scheme and updates live. If your app has its own theme toggle, pass "light" or "dark" from it. During server rendering, "auto" renders light until it mounts.

Placement and accessibility

• The orb is fixed 20px from the right and 24px from the bottom, at z-index 40. The chat panel opens in the same corner at z-index 41. Position is not configurable in this beta, so keep that corner clear or raise your own overlays above 41.
• Everything uses inline styles. There’s no stylesheet to import and no global CSS. On first use Usher adds <style> elements for its animations. They are named with a usher- prefix.
• Accessible names: the orb is “Talk to the assistant” (or “Talk to {title}” when you set title), its Aa button “Type a message”, and its × “End conversation”. In the panel, the message box is “Message the assistant”, the buttons are “Minimize chat”, “End conversation”, and “Jump to latest”, and the panel is a dialog named “{title} conversation”, “Assistant conversation” by default. Enter sends a chat message.
• Testing tip: the orb’s × and the panel’s End button are both named “End conversation”. In Testing Library or Playwright, scope the query: find the panel’s button inside the dialog, for example getByRole("dialog", { name: /conversation/ }), and the orb’s outside it.
• All motion stops when the visitor has prefers-reduced-motion set.

The ref and the runtime

Pass a ref to reach Usher from code. The handle has sendText(text), which runs one local text turn and resolves to its AgentAction, and runtime(). There is one runtime per page, and it outlives <Usher> remounts.

Custom reasoner

Text turns that don’t go through a live session (local mode and ref.sendText) use a rules-based DeterministicReasoner by default. You can pass any object with a name and decide(input) method. Its decisions still pass through the same policy and validation chain, so a custom reasoner can’t reach a page the map doesn’t allow. Don’t put a model API key in the browser to power one.

interface Reasoner {  readonly name: string;  decide(input: ReasonerInput): Promise<ReasonerDecision>;}interface ReasonerInput {  transcript: string;  allowlist: readonly { destination: Destination; score: number }[]; // pick ids from here only  safeContext: SafeContext;  currentLocation: AppLocation;  kbSnippets?: readonly { id: string; title: string; content: string }[];}type ReasonerDecision =  | { tool: "navigate"; destinationId: string; params?: Record<string, unknown>; text?: string }  | { tool: "offer_navigation"; destinationId: string; text?: string }  | { tool: "clarify"; question: string }  | { tool: "answer"; text?: string };