Voice Embed

Developer preview — design only

Voice Embed is a v1.3 design-only item: it has not been implemented and nothing below is a commitment to a specific API shape. This page exists so integrators know it’s coming and roughly what it will look like; treat every detail here as subject to change until an implementation package ships.

What it is

“Our agent in your app”: a small browser SDK plus a server call that lets your backend start a voice, voice+text, or text-only session with one of your web agents, without the browser ever holding a secret key.

The console’s own widget today uses a console-hosted session endpoint authenticated with a publishable key. Voice Embed will move that onto a versioned, documented Service API endpoint and add a server-minted, short-lived client secret for apps that have their own backend — so a page embedding the widget never needs a long-lived credential in client-side code.

How it will work

1. Your backend, holding your project’s secret API key, requests a short-lived client secret for one specific web agent and mode.
2. Your backend hands that client secret to the browser (however your app already gets data to its frontend).
3. The browser calls NaironVoice.connect({ clientSecret }), which exchanges the secret — over a request that carries the page’s real browser Origin — for a session, and starts emitting connection/state/transcript events.

Two request shapes are being reconciled into this one flow: the Service API’s /v1/web-sessions (server-side, secret-key, returns a session token directly — the shape a backend-only integration can already use today) and a browser-facing client-secret exchange for pages that want the browser to connect directly. Both will keep working; the exchange step above is additive on top of what’s already documented.

What you can do today

Nothing embed-specific yet — but the underlying pieces are already live if you want to start integrating early:

• Create a web agent and set its allowed origins (Web widget & text mode).
• Mint a publishable key for it and use the console’s own session endpoint (see the API panel in the Client console) or the Service API’s /v1/web-sessions with a secret key from your backend.
• This is the Client console/API surface, not the Voice Embed SDK below — Voice Embed is the planned, browser-installable packaging of the same capability.

Draft surface (subject to change)

// draft — not published, names and shapes may change
import { connect } from "@nairon/voice-embed";

const session = await connect({
  clientSecret: "nrn_ws_...",
  mode: "WEB_FULL", // or "WEB_TEXT"
});

session.on("connected", () => {});
session.on("agent_state", (state) => {}); // connecting | listening | thinking | speaking
session.on("transcript", (turn) => {});
session.on("error", (err) => {});

session.sendText("Hello");
session.mute(true);
session.end();

No @nairon/voice-embed package exists on npm yet, no Voice Embed endpoint answers requests today, and this preview implies no pricing change.

What’s not decided yet

• The exact embed mechanic (inline script vs. iframe vs. this SDK) and how far its styling can be customized.
• Whether a session-ended webhook ships in the first version or a later one.
• How a session is scoped to a specific project/flow beyond the web agent it targets.

Nothing here is live; there is no /developer/voice-embed/ endpoint or script to include today — this page will be replaced with the real reference once an implementation package ships.