@rydhm/web
v0.3.2
Published
Put a Rydhm voice expert inside any web app: an onboarding coach that talks, sees the page and shows the way, and a softphone for reps whose calls Rydhm transcribes live.
Maintainers
Readme
@rydhm/web
Put a Rydhm voice expert inside your web app.
- Onboarding coach: an expert that talks with your users, knows which page they are on, and shows them the way: it highlights, scrolls, clicks, fills and navigates in your app, runs guides and announces what is new.
- Softphone: a headless browser phone for sales reps. Rydhm transcribes both sides live and suggests the next question.
Small API, typed, safe by default, and a one-line script tag for teams that do not write code.
Early access. The Onboarding coach and rep calls run on Rydhm's staging today (
https://api-staging.rydhm.ai). Copy the install code from your expert's Advanced tab: it already has your key and the rightdata-api-url.
npm i @rydhm/webContents
- Install: script tag (no code)
- Install: npm
- Options
- API
- Events
- Headless mode
- Client tools
- Safety guarantees
- The app map
- Guides and announcements
- Softphone
- Protocol (for server implementers)
- Browser support, size, CSP
Install: script tag (no code)
- In Rydhm, open your expert → Advanced → Website keys, create a key (
rydhm_pk_…) and add your website (for examplehttps://app.example.com) to its allowed websites. - Paste this before
</body>:
<script src="https://cdn.jsdelivr.net/npm/@rydhm/[email protected]/dist/engine.js" data-key="rydhm_pk_…" data-api-url="https://api-staging.rydhm.ai" async></script>That is all: a bubble with your expert's face appears in the corner; one click starts a voice
conversation, and Type in the bubble switches to a typed one (no microphone, no sound: for open
offices and phones without headphones; the bubble remembers the choice). The panel's foot says
"Powered by Rydhm", a small link to rydhm.ai. engine.js is a small loader; it fetches engine-livekit.js (the audio part) from the
same folder only when a conversation starts. Rydhm also serves both files from its app
(https://staging.rydhm.ai/engine.js today); pin a version in production either way.
Every option has a data-* form: data-api-url, data-ui="none", data-position="bottom-left",
data-theme="dark", data-accent="#0f766e", data-language="hi", data-navigate="reload",
data-debug, data-resume="false", data-learn-pages="false", data-user-id, data-user-hash,
data-user-name, and data-auto-init="false" to wait for your own Rydhm('init', …).
Without data-key: Google Tag Manager, a bookmarklet
The tag does not need data-key: Rydhm('init', { key, apiUrl }) starts the SDK, and any data-*
on the tag still applies underneath. In Google Tag Manager, a Custom HTML tag on all pages:
<script>
window.Rydhm=window.Rydhm||function(){(window.Rydhm.q=window.Rydhm.q||[]).push(arguments)};
Rydhm('init', { key: 'rydhm_pk_…', apiUrl: 'https://api-staging.rydhm.ai' });
</script>
<script src="https://staging.rydhm.ai/engine.js" async></script>A tag without data-key needs 0.2.0 or later (on npm from 0.3.0). The snippet loads the app's copy;
a pinned CDN version (https://cdn.jsdelivr.net/npm/@rydhm/[email protected]/dist/engine.js) works the same.
A "Try it on your site" bookmarklet does the same from the address bar, with no deploy (the site must be one of the key's allowed websites):
javascript:(function(){window.Rydhm=window.Rydhm||function(){(Rydhm.q=Rydhm.q||[]).push(arguments)};Rydhm('init',{key:'rydhm_pk_…',apiUrl:'https://api-staging.rydhm.ai'});var s=document.createElement('script');s.src='https://staging.rydhm.ai/engine.js';s.async=true;document.head.appendChild(s)})()Calling Rydhm('init', …) again with the same key returns the same instance, so a tag that fires
twice is harmless. A bad Rydhm('init', …) (no key, a secret key) logs a console error rather than
throwing into your page; Rydhm.init(…) throws, for code that wants to catch it.
Calling it from your page
Add the queue stub first, and every call made before engine.js has loaded is replayed when it
does (the same pattern as Intercom):
<script>window.Rydhm=window.Rydhm||function(){(window.Rydhm.q=window.Rydhm.q||[]).push(arguments)};</script>
<script>
Rydhm('identify', { id: 'user_42', hash: '<%= rydhmHash %>', name: 'Asha' });
Rydhm('setContext', { plan: 'pro', seats: 12 });
Rydhm('on', 'state', (e) => console.log(e.state));
</script>
<script src="https://cdn.jsdelivr.net/npm/@rydhm/[email protected]/dist/engine.js" data-key="rydhm_pk_…" data-api-url="https://api-staging.rydhm.ai" async></script>After load, both styles work: Rydhm('start') and Rydhm.start(). Rydhm.instance is the
instance, Rydhm.Softphone the softphone class. A queued Rydhm('init', { … }) is merged over the
data-* options (the way to pass a function such as your router).
Install: npm
import { Rydhm } from '@rydhm/web';
const rydhm = Rydhm.init({
key: 'rydhm_pk_live_…',
user: { id: user.id, hash: user.rydhmHash, name: user.name }, // hash: computed on your server
navigate: (path) => router.push(path), // React Router, Next.js, Vue Router…
});
rydhm.setContext({ plan: user.plan, role: user.role });
rydhm.registerTool(
'get_invoices',
{ description: 'Recent invoices of this workspace', parameters: { type: 'object', properties: {} } },
async () => (await fetch('/api/invoices')).json(),
);livekit-client is loaded with a dynamic import(), so your bundler splits it out and visitors
who never talk to the expert never download it.
60-second quickstart (coach)
import { Rydhm } from '@rydhm/web';
const rydhm = Rydhm.init({ key: 'rydhm_pk_test_…' });
document.querySelector('#help')!.addEventListener('click', () => rydhm.start());Ask it "how do I invite my team?": it answers, highlights the Invite button, and clicks it when you say so.
Signed users
Turn on Require signed users on the key to stop anyone from claiming another user's id. Your server computes the hash with the workspace's engine user secret (Rydhm → Workspace → Engine user secret) and hands it to the page:
// server (Node)
import { createHmac } from 'node:crypto';
const hash = createHmac('sha256', process.env.RYDHM_ENGINE_USER_SECRET!).update(user.id).digest('hex');Never compute it in the browser. Ids without a valid hash are treated as anonymous (anon_<id>)
and can never read a signed user's progress.
Options
| Option | Type | Default | What it does |
| --- | --- | --- | --- |
| key | string | required | Publishable key rydhm_pk_…. Safe in a web page; works only from its allowed websites. A secret key (rydhm_live_…) is refused. |
| apiUrl | string | https://api.rydhm.ai | API origin. https only (http for localhost). |
| user | { id, hash?, name?, traits? } | anonymous | The signed-in user. traits ≤ 4 KB. |
| ui | 'bubble' \| 'none' | 'bubble' | 'none' draws nothing: build your own UI from the events. |
| position | 'bottom-right' \| 'bottom-left' | expert setting | Bubble corner. |
| theme | 'auto' \| 'light' \| 'dark' | 'auto' | Bubble and spotlight theme. 'auto' follows your page as it changes: a data-theme (or data-color-scheme, data-bs-theme) of dark or light, a dark / light class, or a single color-scheme on <html> or <body>; with none of those, the visitor's system setting. |
| accent | CSS colour | expert setting | Accent colour (#hex, rgb(), hsl(), oklch()). |
| language | BCP 47 | expert's | The language the expert should speak. |
| navigate | (path) => void \| 'auto' \| 'history' \| 'reload' | 'auto' | How the coach changes page. 'auto': pushState + popstate, and a real page load if nothing on the page changed within 700 ms. Other origins are always refused. |
| confirm | (req) => Promise<boolean> | bubble dialog, or window.confirm headless | Ask before a risky click. Resolve true only on an explicit yes. |
| resume | boolean | true | Keep a conversation (voice or typed) going across full page loads (same tab, < 45 s). |
| learnPages | boolean | true | Help an Onboarding coach learn your app (its app map) when the expert asks for it. false never reports. See The app map. |
| duckOnSpeech | boolean | true | In a voice conversation, turn the expert's voice down the moment the person's microphone goes loud over it, before the server has heard them. The server still decides whether it was an interruption (a nod or a cough brings the voice back up). |
| turnstileSiteKey | string | none | When your Rydhm workspace asks for a bot check before a conversation (Cloudflare Turnstile), the SDK renders the page's own window.turnstile (never bundled) with this site key, unless Rydhm sends one. |
| getBotToken | () => Promise<string> | none | Your own way to get the Turnstile token when window.turnstile is not on the page. With neither, the conversation starts without one and fails with bot_check_required. |
| debug | boolean | false | Log protocol traffic to the console. |
API
| Method | What it does |
| --- | --- |
| Rydhm.init(options) | Start the SDK on the page: one bootstrap request, no voice. Same key twice returns the same instance. |
| rydhm.identify(user) | Set or change the user (after login). Reloads guides and announcements for them. |
| rydhm.setContext(obj) | App context the expert should know, ≤ 4 KB JSON (bigger objects are cut and marked _truncated). Live in the conversation within 250 ms. |
| rydhm.track(name, data?) | A custom event: analytics, guide triggers, step completion. Batched. |
| rydhm.registerTool(name, { description, parameters }, handler) | A tool the expert can run in your page. parameters is JSON Schema. Returns an unregister function. |
| await rydhm.start({ mode?, guideId? }) | Start a conversation, optionally with a guide. Call it from a click. mode: 'voice' talks (the mic and the expert's voice); mode: 'text' types, with no mic and no sound, and the coach still shows, clicks and guides on the page. Without a mode: the person's last choice when the expert offers it, else voice. Resolves when the expert has joined; rejects with a code (see errors). |
| await rydhm.stop() | End it. Nothing is billed after this. |
| await rydhm.startGuide(id) | Start a guide from your own button, in the live conversation's mode (else the default one). |
| await rydhm.setMode(mode) | Talk ('voice') or type ('text'), remembered in this browser. A live conversation in the other mode is replaced by one in this mode; its guide carries on. |
| await rydhm.mute(on) | Mute or unmute the mic. |
| await rydhm.send(text) | Type a message into the live conversation (a voice conversation hears it as if said), or start a typed one when none is live. Waits until the expert is ready to read it. |
| rydhm.levels() | { input, output } audio levels 0..1, for your own visualiser. |
| rydhm.state | The current StateEvent. |
| rydhm.on(event, cb) | Subscribe; returns the unsubscribe function. |
| rydhm.destroy() | Remove everything: conversation, bubble, listeners, history patches. |
Events
| Event | Payload |
| --- | --- |
| state | { state: 'idle' \| 'connecting' \| 'listening' \| 'thinking' \| 'speaking' \| 'reconnecting', mode?, sessionId?, muted, retrying? }: retrying while the SDK connects a second time by itself after a failed first connection |
| transcript | { id, speaker: 'user' \| 'expert', text, final }: interim updates share the id of their final line |
| tool | { callId, name, args, status: 'started' \| 'ok' \| 'error', result?, error?, source: 'browser' \| 'worker' } |
| guide | { type: 'offer', guide, reason, accept(), dismiss() } or { type: 'started' \| 'step_completed' \| 'completed', guideId, stepId?, stepsDone, source } |
| announcement | { type: 'shown', announcement, accept(), dismiss() } or { type: 'clicked' \| 'dismissed', announcement } |
| error | { code, message, fix?, status?, retryAt? } |
| sources | { turnId?, sources: [{ documentId, title, url }] }: the knowledge an answer came from (at most 3; url only for a web page, https). The bubble shows them as chips under the answer. |
Error codes: invalid_key, key_not_allowed (add the site to the key's allowed websites),
signed_user_required, rate_limited, offline, network_error (unreachable, or a CORS refusal:
the browser cannot tell them apart), mic_denied (fix says how to unblock it in
this browser), mic_unavailable, audio_blocked (the next tap anywhere unlocks it),
session_failed, expert_unavailable, connection_lost, bootstrap_failed, server_error, and, when anconversation starts: daily_session_cap (429: this site's assistant has had all its conversations forntoday; retryAt says when it can again), daily_voice_minutes_cap (429: voice is out of minutes forntoday, typing still works; retryAt), bot_check_required (403: the workspace asks for a bot check andnnone was given: add Cloudflare Turnstile to the page, or getBotToken), bot_check_failed (403: the`ncheck did not pass; reload and try again).
Headless mode
With ui: 'none' nothing is drawn, and everything still works: the spotlight still highlights,
risky clicks still ask (your confirm, or window.confirm), and the events carry what you need:
const rydhm = Rydhm.init({ key, ui: 'none', confirm: (req) => myDialog.ask(`${req.label}? (${req.reason})`) });
rydhm.on('state', ({ state }) => orb.dataset.state = state);
rydhm.on('transcript', (t) => captions.upsert(t.id, t.speaker, t.text, t.final));
rydhm.on('announcement', (e) => e.type === 'shown' && banner.show(e.announcement, e.accept, e.dismiss));
rydhm.on('guide', (e) => e.type === 'offer' && nudge.show(e.guide.name, e.accept, e.dismiss));
setInterval(() => orb.style.setProperty('--level', String(rydhm.levels().output)), 50);Client tools
The expert (the Rydhm worker) calls tools in the page over LiveKit RPC method rydhm.tool with
{ "callId", "name", "args" }; the SDK answers { "ok": true, "result": … } or
{ "ok": false, "error": "…" }. Replies are JSON and at most 15 KB (larger results are shortened
to { truncated: true, text }). Each call answers inside the caller's timeout (10 s by default, less
1 s of headroom). Only agent participants can call tools.
| Tool | Args | Does |
| --- | --- | --- |
| navigate | { to } | Opens a page on this site (your navigate router, else pushState, else a page load). Other origins and non-http(s) links are refused. |
| highlight | { target, message? } | Spotlight: the page dims around the element, a soft ring pulses on it, and a tooltip says message. Follows scroll/resize; goes away on the next highlight, a click, Escape or after 15 s. Respects reduced motion. |
| scroll_to | { target } | Scrolls the element to the middle of the screen. |
| click | { target } | Clicks it (asks first when it is risky, see below). |
| fill | { target, value } | Types into a field the way a person would (React, Vue and Angular see the change). Never touches secret or payment fields. |
| read_screen | {} | What is visible: headings, buttons, links, inputs, each with a target; ≤ 4 KB. Marked kind: 'page_content'. |
| show_message | { text } | Shows a note in the bubble (and a tool event headless). |
| press_key | { key, target? } | Presses Enter, Escape, Tab, an arrow, Backspace or Space on the target (else what has focus), with what the browser would do: Enter submits a field's form, Space presses a button, Tab moves focus, the arrows move in a select, radio group or list, Escape closes what is open. Enter that submits a payment form asks first. |
| hover | { target } | Moves the pointer over it and says what appeared (a menu with its items, a tooltip). Nothing is clicked. |
| drag | { target, to? , dx?, dy? } | Drags it to another target, or by an offset: pointer events in small steps and, for a native draggable, HTML5 drag and drop (dnd-kit, hello-pangea/dnd, SortableJS). Checked: it moved. A drop on Trash, Delete or Archive asks first. |
| look | { target?, question? } | Screen vision, off unless the expert has it switched on (Page tools → "See charts and icons", or toolPolicy.screenVision: 'on'). Takes a small picture of the target (a chart, an image, a section; a heading means the box it heads), of what is in view (no target), or of the buttons that show only an icon (target: "icons"), and keeps it for the expert to fetch in parts; the expert's vision model describes it. See "Screen vision" below. |
fill types into rich editors (Lexical, ProseMirror/TipTap, Slate, Quill, CodeMirror) the way the keyboard does. A click on a file upload opens the person's file picker (a browser opens it only from their own press, so it may say they must press it); a file is never chosen for them. A press whose effect does not show on the page (a copy, a download, a send) is pressed once and said so, never pressed again.
Targets are, in order: a page-map name from Rydhm (its CSS selector, then its visible-text
hint), a CSS selector, or text:<visible text> (the best match among visible, enabled,
interactive elements; exact beats prefix beats contains; hidden elements never match). A target
that does not resolve is reported as a target_missing event so the page map can be fixed.
Custom tools run after the built-ins: registerTool(name, { description, parameters }, handler).
The handler gets (args, { callId, signal }); signal aborts when the expert stops waiting.
WebMCP
WebMCP lets a page declare tools to the browser's own
AI agents. It is a W3C Community Group draft that still changes (in 2026 navigator.modelContext
moved to document.modelContext, and a registration is undone by aborting its signal), so the SDK
feature-detects it and does nothing in a browser without it.
- Your
registerTooltools are WebMCP tools too. When the browser hasdocument.modelContext(ornavigator.modelContext),rydhm.registerTool(…)also callsmodelContext.registerTool({ name, description, inputSchema, execute }, { signal }), and the function it returns unregisters both. A browser that refuses is ignored. - Your WebMCP tools are the expert's. During a conversation the SDK reads
modelContext.getTools()(again ontoolchange) and offers each tool to the expert as a custom tool, run throughmodelContext.executeTool(…): up to 12, each with a description and an object schema of at most 4 KB, named the way custom tools are (addToCartbecomesadd_to_cart). Never a built-in's name, and never one of yourregisterTooltools twice. An MCP-style result ({ content: [{ type: 'text', text }] }) reaches the expert as{ text };isErroras an error. - Destructive ones ask first. A tool marked
annotations.destructiveHint, or whose name says delete, pay, send… (the risky-click words) and is not markedreadOnlyHint, shows the confirm card and runs only on a yes, said, typed or clicked, exactly once. - Loaded with the conversation, never with the page's script.
- A browser without WebMCP can be given it by a polyfill that defines
document.modelContext(ornavigator.modelContext) with the draft'sregisterTool(tool, { signal }),getTools(),executeTool(tool, args)and atoolchangeevent; the SDK uses whichever is there. The conformance fixturee2e/coach/apps/hashcarries a 30-line one.
Screen vision (look)
read_screen reads the page's structure, which says nothing about a chart drawn on a <canvas>, a
picture, a map, or a button that is only an icon. With look on, read_screen also lists pictures
(charts, images, canvases: their targets) and icons (icon-only buttons with no name yet), and look
pictures what the expert asks about, entirely in the browser (no screen-sharing prompt):
- a
<canvas>gives its own pixels; anything else is copied with its computed styles and drawn through an SVG<foreignObject>; fixed and sticky bars are drawn where they are on screen; - at most 768 px on its longest side, a JPEG of at most 150 KB, kept for a minute while the expert
fetches it in parts (
look_part, each under the 15 KB RPC cap); - never in a picture: what is typed in a field or an editor (drawn empty), password and payment
fields,
data-rydhm-privateareas and the SDK's own UI (grey boxes), other sites' frames and images this page may not read (grey boxes). Web fonts fall back to system fonts.
Icon-only buttons are drawn as one numbered sheet; the expert's vision model names each, and the names
come back (look_names): from then on that button is called so in read_screen, as a target, and in
the app map (names only, its usual rules), and the same icon keeps its name for the rest of the tab
(session storage). A browser that will not read back a <foreignObject> drawing (Safari has refused
to) gets a plain "cannot picture that part" answer; canvases still work there. Tested in Chromium.
Safety guarantees
These live in the SDK, in the browser, so a prompt injection that reaches the model cannot turn them off:
fillrefusestype=password,type=hidden,type=file, everyautocompletepayment token (cc-*,transaction-*),current-password,new-password,one-time-code, fields whose name, id, label or placeholder say card, CVV/CVC, expiry, IBAN, routing or account number, SSN, password, PIN, OTP, API key or secret, every field in a form that collects card details, and hidden, disabled or read-only fields.- Risky clicks ask first. A click on an element whose text, aria-label, title, value, name, id,
test id, href or form action says delete, remove, pay, buy, purchase, checkout, place order,
cancel subscription, close account, transfer, refund, withdraw, unsubscribe, upgrade, downgrade,
deactivate, disable, reset, revoke, disconnect, uninstall, approve, reject, archive, merge, deploy,
publish, charge, sign out, email everyone (and more: see
RISKY_PHRASES), in English, Hindi, Spanish, German, French or Portuguese; send, invite, share or post as the final step (inside a dialog or form: on the page they only open the composer); a button styled as dangerous or whose description warns it cannot be undone; a link to another website; or a submit button of a payment or password form or one whose heading says payment or checkout, shows a confirm. A button that only opens a menu or dialog does not ask: the action inside it does. The confirm takes a yes or no said or typed in the same six languages; a question is never a yes, and a spoken "okay" (or "hmm", "so", "vale"…) on its own waits 1.5 s for the rest of the sentence, which is then judged with it. It clicks only on Yes. No answer before the expert's timeout means no click. Adddata-rydhm-confirmto any element to always ask. read_screennever reads the value of password, payment, one-time-code, hidden or private fields (it saysprotected: true), cuts to 4 KB, and labels the result as page content: data, not instructions.data-rydhm-privateon any element hides that subtree from every tool: never read, clicked, filled, highlighted or pictured.lookpictures (only when the expert has it on) never show typed values, payment or password fields, private areas or other sites' content (see "Screen vision").navigatestays on your origin.- Tool calls are accepted only from the expert (an agent participant);
rydhm.eventsonly from the expert or the Rydhm server. - Page URLs are sent without their query string (tokens and personal data often live there); a hash
is kept only when it is a hash route (
#/settings). - The bubble and spotlight live in Shadow DOM and set every string with
textContent; nothing from the API or the model is ever parsed as HTML. - The bubble's pointer, focus and key events stop at its own element, so clicking it never closes a
dialog your app has open ("click outside" handlers on
document), and typing in it never fires your app's keyboard shortcuts. Your capture-phase listeners ondocumentstill see them. - The only network traffic is to
apiUrland the LiveKit URL the API returns (plus the expert's face image URL the API returns).
The app map
An Onboarding coach learns your app by itself, so you do not have to name CSS targets for it. When
bootstrap says learnPages (the coach's app map setting in Rydhm, on by default), the SDK reads each
page once it has settled — after load and after each route change, once the page has been quiet
for about 1.75 s — and sends one report to POST /v1/engine/page-inventory: the page's path and
title, its h1–h3 headings, navigation items, buttons, tabs, same-site links with their path, and
form fields by their label. The coach then knows which page has what ("Invite people is on
/settings/team") and can open the right page and point at the button from anywhere.
What it never sends, by rule:
- No values. Never what someone typed or chose, never a select's chosen option, never the text
of an editor; a field is reported by its label (or
aria-label/ placeholder) only. - No sensitive fields at all: password, hidden, file, payment (
cc-*) and secret / one-time-code fields. - Nothing inside the SDK's own UI,
data-rydhm-private, ordata-rydhm-ignore(this one hides a subtree from the app map only; on<body>or<html>it skips the whole page). - No record names. Ids in paths (numbers, UUIDs, long hex, id tokens, emails, slugs with an id)
become
*:/projects/42is learned as/projects/*. A link to such a path is sent by its path pattern only, never its text, and nothing else inside that link's row or card (li,tr,article) is sent. A record's own page keeps no title and no h1. Table bodies, grids, listboxes and feeds are your data, so nothing in them is read. - No personal data. Names that look like emails, @handles, phone numbers, long digit runs, ids,
amounts of money, dates and times or URLs are dropped, as are the signed-in person's name and id
and the string values of your context and traits (except plan, role, tier, status, locale,
language, country). Bracketed counts are cut (
Inbox (12)→Inbox); names are at most 80 characters. - No user. The report carries no user id or traits: the map is your app's, not a person's.
How often: at most once per page pattern per browser per 24 hours, and 30 reports per browser per day
in all (in local storage; without it, once per pattern per page load). It is a beacon
(sendBeacon, text/plain, the key as ?key=), so it needs no preflight and never slows the page.
The API applies the same rules again to whatever arrives. Turn it off for the expert in Rydhm, or
for one site with learnPages: false / data-learn-pages="false".
Teach mode and Test mode (0.3.0)
Most coaches live behind a sign-in, which nobody can crawl, so the admin teaches the coach by
clicking through the app once: Teach it your app in the coach's Setup tab opens the app with
#rydhm-teach=<token> (30 minutes). The SDK takes the token out of the address at once, checks it
with the API and keeps it in session storage (that tab only), and shows a small bar at the bottom of
the page, clear of the launcher: "Teaching : open your main screens — N screens learned ·
Done" (0.3.1). Drag it by its grip anywhere in the window (or focus the grip and use the arrow keys;
a double-click puts it back), or Minimise it to a "N learned" pill; where it is and whether it is
folded last the teaching session. It loads only in a teaching tab (with engine-livekit.js in the
script tag). While teaching, every
screen is reported at once, with the screen's own words: headings, short help text and paragraphs
(300 characters at most), empty-state copy, and button, tab and menu labels — at most 2.5 KB a
screen. The same rules as above apply, and more: never tables, grids or lists of records, nothing in a
record's row or card, no fields or values, no editors or code, and on a record's own page
(/projects/*) headings and actions only. Done ends it; the coach writes what it learned up as one
knowledge document, "Inside ", which you can read and delete in Knowledge.
A new coach starts in Test mode ("Only me"): the tag can go on your live app, and the coach shows
only in browsers opened with a teach link or a Preview on my site link (#rydhm-preview=<token>,
kept 7 days in that browser), until you switch it to Everyone. Everyone else's page shows nothing:
bootstrap says audience: 'testing', and sessions are refused.
Guides and announcements
Both come from the bootstrap call (configured in Rydhm, no code):
- Announcements show as a small card above the bubble ("We launched X. Want me to show you?").
The button starts the linked guide, by voice or typed as the person last chose. Each one is shown at most 3 times, at most once a
day, and never again after a click or dismiss (per announcement, remembered in
localStorage). Shown/clicked/dismissed are reported. - Guide triggers are evaluated in the page:
first_visit(the first time this browser sees a matching page),page(a matching page view),event(atrack()name),stuck(N seconds of visible time on one page). A trigger offers the guide as a one-line nudge; the conversation starts only on the person's click. Each guide is offered at most 3 times, 12 h apart, never after it is dismissed or completed. - Steps complete in the page when their
completeWhenhappens: a page view ({ type: 'page', pattern }), a click on a target ({ type: 'click', target }) or an event ({ type: 'event', name }). The SDK reportsstep_completedand keepsrydhm.guidecurrent for the expert; the expert's ownguide.*events arrive onrydhm.events.
Path patterns: * matches inside one path segment, ** across segments, /settings/* also
matches /settings. Hash routes (#/x) count as the path.
Softphone
For reps whose calls Rydhm transcribes. Headless: your app draws the UI.
import { Softphone } from '@rydhm/web';
// Your server calls POST /v1/reps/:externalId/softphone-token with your SECRET key
// and hands the reply ({ url, token, presenceRoom, expiresAt }) to the rep's browser.
const phone = new Softphone({
token: await fetch('/api/rydhm/softphone-token').then((r) => r.json()),
refreshToken: () => fetch('/api/rydhm/softphone-token').then((r) => r.json()),
});
phone.on('incoming', (call) => ui.ring(call.from, { answer: call.answer, decline: call.decline }));
phone.on('transcript', (t) => ui.line(t.id, t.speaker, t.text, t.final)); // speaker: rep | prospect | ai
phone.on('suggestion', (s) => ui.suggest(s.text));
phone.on('timer', (t) => ui.timer(t.seconds));
phone.on('ended', (e) => ui.ended(e.outcome, e.durationSec));
// Outbound: your server calls POST /v1/rep-calls and passes its reply here.
await phone.join(await fetch('/api/calls', { method: 'POST', body }).then((r) => r.json()));
await phone.mute(true);
await phone.hangup();Join-only, without a softphone token. To put the rep's browser on outbound calls only, skip the
softphone token: new Softphone({ apiUrl }), then join() the join that POST /v1/rep-calls
returned (or its whole reply). Everything that talks to the API as the rep needs the token and says
so: connect() (going online for callbacks) and decline() reject, and hangup() leaves the call
in this browser, then rejects because the prospect is still on the line. End it for both sides from
your server (POST /v1/rep-calls/:id/hangup), or pass refreshToken and connect() fetches the
first token itself.
const phone = new Softphone({ apiUrl: 'https://api.rydhm.ai' });
const call = await fetch('/api/calls', { method: 'POST', body }).then((r) => r.json()); // { id, join, … }
await phone.join(call);Closing the tab (pagehide / beforeunload) leaves the presence room and any call room at
once, so LiveKit drops the rep right away and a callback is never rung on a closed browser. A page
that stays (a cancelled unload, the back/forward cache) goes online again by itself. A browser that is
killed outright sends nothing; LiveKit then notices on its own a little later.
60-second quickstart (softphone)
Open demo/softphone.html from this package, paste the softphone-token reply your server got, and
press Go online. Callbacks ring there; Answer joins the call with the mic.
| Member | What it does |
| --- | --- |
| new Softphone({ token?, url?, apiUrl?, refreshToken?, inputDeviceId?, autoConnect?, debug? }) | token is the softphone-token reply (or its token string plus url). Goes online right away unless autoConnect: false. Without token it is join-only (above). |
| connect() / disconnect() | Go online / offline (presence). Reconnects with backoff, refreshing the token when it expired. Needs the token. |
| join(call) | Join a call room: the POST /v1/rep-calls reply ({ id, join }) or { url, token, callId? }. Publishes the mic. Works without the softphone token. |
| answer(callId?) / decline(callId?) | For a ringing call (the newest when no id). Decline posts POST /v1/rep-calls/:id/decline (needs the token). |
| hangup() | POST /v1/rep-calls/:id/hangup, then leaves the room. Without the token: leaves the room only, then rejects saying so. |
| mute(on = true), setInputDevice(id), Softphone.inputDevices() | Mic control. |
| state, duration, incoming, levels() | { presence, call, callId?, muted, quality, startedAt?, durationSec }, seconds, ringing calls, audio levels. |
| on(event, cb) | state, incoming, transcript, suggestion, answered, voicemail (kind: detected \| beep \| left), ended, timer, event (every raw event), error. |
| destroy() | Leave everything (does not hang the call up for the other side). |
How incoming calls reach the browser: the softphone token joins the rep's presence room
(rep_presence_<repId>, subscribe and data only, no agent). Being in that room is being online.
The API announces a callback there as call.incoming on topic rydhm.events, with
data.join = { url, token } for the call's own room and data.ringSeconds. A call that is not
answered in time ends as missed.
Protocol (for server implementers)
All wire names live in src/protocol.ts and follow
docs/engine/design-2026-11-11.md.
- Answer a refused origin with
403and CORS headers for that origin, so the page can say "not available on this site"; a response without CORS headers reaches the SDK only as a network error. GET /v1/engine/bootstrap?userId&hash&path(Bearer = publishable key) →{ expert: { id?, name, faceUrl? }, bubble?: { enabled?, position?, theme?, accent?, label?, launcherText?, modes?, poweredBy? }, announcements?, guides?, pageMap?, clientTools? }.POST /v1/engine/sessions{ mode, user, context, guideId?, language?, page, tools }→{ sessionId, livekit: { url, token }, expert?, clientTools?, pageMap?, guide? }. The LiveKit token needscanUpdateOwnMetadata(the SDK sets attributes) andcanPublishData(typed messages onlk.chat).POST /v1/engine/events{ user, events: [{ type, name?, data?, at }] }. The unload flush usessendBeacon, which cannot send headers: it carries the key as?key=and askeyin atext/plainJSON body.POST /v1/engine/page-inventory{ path, title?, items: [{ kind, name, selector?, path? }] }(≤ 120 items;kind: heading, nav, button, tab, link, field), sent as a beacon the same way, only while bootstrap sayslearnPages: true. 202; 403app_map_offwhen the expert does not learn.- Teach mode (0.3.0): the same route with
{ …, teach, text: ['# Heading', '[Button]', 'text'] }, sent withfetch(Bearer), answers{ accepted, screens };POST /v1/engine/teach/done { teach }. Bootstrap takes?preview=<token>and answersaudience(testing|everyone) andpreview({ kind, expiresAt }or null); sessions takepreviewand answer 403coach_testingwithout one while testing. - Participant attributes set by the browser:
rydhm.page({url,path,title}),rydhm.context(≤ 4 KB),rydhm.tools(custom tools[{name,description,parameters}]),rydhm.guide({id,stepsDone}). - The SDK reads LiveKit Agents' standard
lk.agent.state,lk.transcriptionstreams and acceptsrydhm.eventsas data packets or text streams.
Browser support, size, CSP
- Current Chrome, Edge, Firefox and Safari (desktop and mobile; iOS Safari 15+). Needs WebRTC, Shadow DOM and Custom Elements. The script bundle targets ES2019.
- Size, 0.3.0: the script tag loads
dist/engine.js, 183 KB raw, 59.9 KB gzip (the build fails past 60 KB gzip). The LiveKit part,dist/engine-livekit.js(722 KB raw, 202 KB gzip, with the screen reader), is fetched from the same folder only when a conversation (voice or typed) starts, so idle visitors never download it.data-livekit-srcpoints it somewhere else. With npm, LiveKit is a dynamic import your bundler splits out the same way. - Content Security Policy: allow the script's origin in
script-src(it serves bothengine.jsandengine-livekit.js; anonceon theengine.jstag is copied to the second file),apiUrlplus your LiveKit host (wss:andhttps:) inconnect-src, and the face image host inimg-src. Styles use constructable stylesheets (no'unsafe-inline'needed in modern browsers). Sites that enforce Trusted Types addrydhmto theirtrusted-typespolicy list. - No cookies, no external fonts, no third-party requests.
Development
pnpm --filter @rydhm/web build # dist/*.js + .d.ts (tsc), dist/engine.js and dist/engine-livekit.js (esbuild)
pnpm --filter @rydhm/web typecheck
pnpm --filter @rydhm/web test # vitest + happy-domThen serve the package folder (for example npx serve packages/web) and open /demo/index.html
(set its data-key to a staging publishable key that allows that origin) or /demo/softphone.html.
