writing/tutorial/2026/11
● TutorialNov 20, 2026·16 min read

Build a Live AI Video Host for Your Website with Nuance Live

We built a talking AI video host for noqta.tn in one evening with the Nuance Live API: a token server, a page that runs the call, and two tools that put a service card and prefilled contact options on the visitor's screen. Here is the full code, what it cost, and the limits we hit.

A visitor lands on a services page, presses a button, and a person on video says hello, asks what their business does, and puts the right service on their screen while still talking. When the visitor wants to talk to the team, the host asks for their name and need, then shows a WhatsApp button with the message already written.

That is what we built for noqta.tn on 20 November 2026 with Nuance Live, a new real-time API from Nuance Labs for AI personas that talk on live video. This tutorial gives you the full working code, what one call cost, and the limits that decide where it can and cannot go on a real site.

What You Will Build

  • A small Node.js server that keeps your API key secret and mints a single-use session token for each call.
  • A web page that starts the call, shows the persona's video, and writes a live transcript.
  • A host prompt that makes the persona a front-desk host for your company.
  • Two tools the persona can use while it talks: show_service puts a service card on the screen, and show_contact shows contact options with the visitor's name and need filled in.

The whole thing is two files and no build step. The full code is on GitHub: nooqta/nuance-live-ai-host-demo.

Prerequisites

  • Node.js 18 or newer (the server uses the built-in fetch).
  • A Nuance Labs account and an API key from the dashboard. Keys start with nk_.
  • A browser on localhost or https. Browsers give a page the microphone only in a secure context.
  • Basic JavaScript. Familiarity with WebRTC helps but is not required: the SDK handles the media room for you.

How Nuance Live Works

Nuance Live runs the conversation inside a LiveKit media room. Your code does three things:

  1. Your server calls POST https://api.nuancelabs.ai/session-tokens with the API key. The token fixes everything about the call: the persona's face, its prompt, and its tools. It starts one conversation, within 60 seconds.
  2. Your page gives that token to the JavaScript SDK @nuancelabs/js-sdk, which creates the conversation, waits for the persona to get ready (up to about half a minute), joins the room and turns on the microphone.
  3. During the call, events go both ways on a data channel: transcripts and tool calls come in, and your page sends instructions, typed messages and tool results back.

The API key never reaches the browser. If it did, anyone could mint calls on your credits.

Step 1: Check Your Plan Before Writing Code

Your plan sets three numbers that shape the design. Read them with your key:

curl -s https://api.nuancelabs.ai/usage \
  -H "Authorization: Bearer $NUANCE_API_KEY"

On our key, on 20 November 2026, it answered:

{
  "limits": { "concurrent_sessions": 1, "daily_credits": 60, "hourly_conversations": 60 },
  "credits": { "used": 0, "remaining": 60, "renews_at": "2026-11-21T00:00:00" }
}

So: one call at a time, 60 credits a day, and 60 starts an hour. Our test call of about a minute and a half, with two visitor turns and both tools used, took 6 credits. That is fine for a demo and a few sales calls a day. It is not enough for an open button on a busy page. Plan for that before you put it in front of the public.

Step 2: Set Up the Project

mkdir nuance-demo && cd nuance-demo
printf 'NUANCE_API_KEY=%s\n' "nk_your_key_here" > .env
chmod 600 .env

Keep .env out of git. The server reads it at start-up, so no package is needed.

Step 3: Write the Host Prompt

The persona's prompt is personality.system_prompt. Write it like a briefing for a person on the phone: who they are, what they do, what they must not do, and when to use each tool.

const SERVICES = [
  ["ai-agents", "AI support and operations agents", "Agents that answer customers on WhatsApp, the website and email, and do back-office tasks."],
  ["automation", "Workflow automation", "Connect the tools a company already uses so repetitive steps run on their own."],
  ["analytics", "Power BI and smart analytics", "Dashboards on top of company data, with an AI layer you can ask questions in plain words."],
  ["web-apps", "Websites and custom apps", "Business websites, portals and mobile apps, built multilingual and right-to-left ready."],
  ["einvoicing", "E-invoicing integration", "Connecting invoicing systems to Saudi ZATCA and similar e-invoicing platforms."],
  ["agentx", "AgentX", "Our own platform that runs a team of AI agents for a company, each with its own job."],
];
 
const SYSTEM_PROMPT = (name) => `You are ${name}, the front-desk host on the Noqta website. Noqta is a software and AI company based in Tunisia that works with small and mid-size companies in Tunisia, Saudi Arabia and the Gulf. You are warm, brief and plain-spoken. Keep every reply to two or three short sentences, then ask one question.
 
Your job: find out what the visitor's business does and what slows it down, point them to the one Noqta service that fits, and offer a free call with the team.
 
Noqta services:
${SERVICES.map(([, t, d]) => `- ${t}: ${d}`).join("\n")}
 
Rules:
- When you name a service to the visitor, hand it off so it shows on their screen. Say "Let me put that on your screen", not "it's there".
- When the visitor wants to talk to the team, get a quote or book a call, ask for their first name and what they need in one line, then hand it off to show the contact options. Say you are bringing up the options.
- You don't know prices. Noqta gives a quote after a short call. Say so if asked.
- You do not give tax, legal or financial advice. For e-invoicing rules, say the team confirms what applies to their case on the call.
- If you don't know something, say so and offer the call.`;

Three lines in it matter more than they look:

  • "Say 'Let me put that on your screen', not 'it's there'." The persona speaks before your tool runs. If it says "done", it says it before anything is done.
  • "You don't know prices." Without it, a voice model will guess a price to be helpful. A guessed price on your own website is worse than no answer.
  • "You do not give tax, legal or financial advice." The platform refuses prompts that ask for this kind of advice, and it is the right rule for a sales host anyway.

Tip: the persona has no name until the prompt gives it one. persona_id picks only the face and voice.

Step 4: Write the Token Server

The server does four jobs: serve the page, mint a token, show your remaining credits, and list the services for the page. Save it as server.mjs.

// Nuance Live demo: serves index.html and mints session tokens.
import { createServer } from "node:http";
import { readFileSync } from "node:fs";
import { createHash } from "node:crypto";
 
const dir = new URL(".", import.meta.url).pathname;
for (const line of readFileSync(dir + ".env", "utf8").split("\n")) {
  const m = line.match(/^(\w+)=(.*)$/);
  if (m) process.env[m[1]] ??= m[2];
}
const API = "https://api.nuancelabs.ai";
const KEY = process.env.NUANCE_API_KEY;
const PORT = Number(process.env.PORT ?? 5177);
const PERSONAS = ["sam", "sonia", "mira"];
const NAMES = { sam: "Sami", sonia: "Sonia", mira: "Mira" };
 
// SERVICES and SYSTEM_PROMPT from Step 3 go here.
 
const TOOLS = [
  {
    type: "function",
    name: "show_service",
    description: "Shows one Noqta service card on the visitor's screen.",
    parameters: {
      type: "object",
      properties: { service: { type: "string", enum: SERVICES.map(([id]) => id) } },
      required: ["service"],
    },
  },
  {
    type: "function",
    name: "show_contact",
    description: "Shows the contact options (WhatsApp, contact form) with the visitor's name and need filled in.",
    parameters: {
      type: "object",
      properties: { first_name: { type: "string" }, need: { type: "string" } },
      required: ["need"],
    },
  },
];
 
async function mint(persona, visitor) {
  const r = await fetch(`${API}/session-tokens`, {
    method: "POST",
    headers: { Authorization: `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({
      interface: "nuance_live",
      personality: { persona_id: persona, system_prompt: SYSTEM_PROMPT(NAMES[persona]) },
      interface_setup: {
        delegation: {
          type: "responses",
          responses: {
            model: "default",
            instructions:
              "Call show_service with the one service the persona named. Call show_contact when the visitor wants to talk to the team. Answer in one short sentence.",
            tools: TOOLS,
            reasoning: { effort: "low" },
          },
        },
        video: { input: { camera: false } },
        runtime_tools: { end_call: true },
      },
      end_user_id: createHash("sha256").update(visitor).digest("hex").slice(0, 32),
    }),
  });
  const text = await r.text();
  if (!r.ok) throw new Error(`${r.status} ${text}`);
  const body = JSON.parse(text);
  if (body.warnings?.length) console.warn("mint warnings:", JSON.stringify(body.warnings));
  return body.token;
}
 
createServer(async (req, res) => {
  const url = new URL(req.url, "http://localhost");
  try {
    if (req.method === "POST" && url.pathname === "/api/token") {
      const asked = url.searchParams.get("persona");
      const persona = PERSONAS.includes(asked) ? asked : "mira";
      const token = await mint(persona, req.socket.remoteAddress ?? "local");
      res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify({ token }));
    } else if (url.pathname === "/api/usage") {
      const r = await fetch(`${API}/usage`, { headers: { Authorization: `Bearer ${KEY}` } });
      res.writeHead(r.status, { "Content-Type": "application/json" }).end(await r.text());
    } else if (url.pathname === "/api/services") {
      res.writeHead(200, { "Content-Type": "application/json" }).end(JSON.stringify(SERVICES));
    } else if (url.pathname === "/") {
      res.writeHead(200, { "Content-Type": "text/html" }).end(readFileSync(dir + "index.html"));
    } else res.writeHead(404).end();
  } catch (e) {
    console.error(new Date().toISOString(), String(e));
    res.writeHead(500).end(String(e.message ?? e));
  }
}).listen(PORT, () => console.info(`Nuance demo on http://localhost:${PORT}`));

What each setting does:

  • delegation.type: "responses" puts a backend reasoner behind the persona. When the persona hands off a task, the backend decides which of your tools to call and with which arguments. Your page runs the tool and sends the result back.
  • tools must sit inside delegation.responses. Tools at the top level of the body are ignored, and the response's warnings says so. Read warnings every time you mint: it is the only report of a dropped tool.
  • video.input.camera: false stops the persona from using the visitor's camera. A sales host does not need to see the visitor, and fewer permission prompts mean more people stay.
  • runtime_tools.end_call: true lets the persona hang up after saying goodbye.
  • end_user_id is your id for the person. Hash anything personal first. We hash the IP address for the demo; on a real site, use your own session id.

Step 5: Build the Page

Save this as index.html next to the server. The styles are left out here to keep the code short; any layout with a video, a card area and a transcript works.

<video id="avatar-video" autoplay playsinline></video>
<audio id="avatar-audio" autoplay></audio>
<div id="status">Idle</div>
<select id="persona">
  <option value="mira">Mira</option>
  <option value="sonia">Sonia</option>
  <option value="sam">Sam</option>
</select>
<button id="start">Start call</button>
<button id="hang-up">Hang up</button>
<div id="cards"></div>
<div id="transcript"></div>
import { createNuanceConversation } from "https://esm.sh/@nuancelabs/js-sdk@0.37.1";
 
const $ = (id) => document.getElementById(id);
const services = Object.fromEntries(
  (await (await fetch("/api/services")).json()).map(([id, t, d]) => [id, { t, d }]),
);
const setStatus = (s) => ($("status").textContent = s);
const esc = (s) => String(s ?? "").replace(/[&<>"]/g, (c) =>
  ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]);
 
let conversation = null;
let line = null;
 
function say(text) {
  const p = document.createElement("p");
  p.textContent = "Host: " + text;
  $("transcript").append(p);
  return p;
}
function card(html) {
  const d = document.createElement("div");
  d.className = "svc";
  d.innerHTML = html;
  $("cards").prepend(d);
}
 
$("start").onclick = async () => {
  if (conversation) return;
  const persona = $("persona").value;
  conversation = createNuanceConversation({
    token: async () => {
      const r = await fetch(`/api/token?persona=${persona}`, { method: "POST" });
      if (!r.ok) throw new Error(await r.text());
      return (await r.json()).token;
    },
    mediaDevices: { cameraEnabled: false },
    maxSessionSeconds: 300,
  });
 
  conversation.onChange((e) => {
    if (e.type === "state-changed") setStatus(e.state);
    if (e.type === "avatar-preparing") setStatus("Host is getting ready…");
    if (e.type === "tracks-changed") {
      conversation.avatar.videoTrack?.attach($("avatar-video"));
      conversation.avatar.audioTrack?.attach($("avatar-audio"));
    }
    if (e.type === "avatar-presented") {
      setStatus("Live");
      conversation.sendInterfaceEvent({
        type: "response.create",
        response: { instructions: "Welcome the visitor to Noqta, say your name, and ask what their business does." },
      });
    }
    if (e.type === "time-remaining") setStatus(`Live · about ${Math.round(e.secondsRemaining / 60)} min left`);
    if (e.type === "session-ended") { setStatus(`Ended: ${e.reason}`); conversation = null; }
  });
 
  conversation.onInterfaceEvent((e) => {
    if (e.type === "session.output_transcript.delta") {
      line ??= say("");
      line.textContent += String(e.delta);
    }
    if (e.type === "session.output_audio.done") line = null;
  });
 
  conversation.onToolCall((call) => {
    const a = call.arguments ?? {};
    if (call.name === "show_service" && services[a.service]) {
      const s = services[a.service];
      card(`<b>${esc(s.t)}</b> ${esc(s.d)}`);
      conversation.sendToolResult(call.callId, { shown: s.t });
    } else if (call.name === "show_contact") {
      const msg = `Hello, I'm ${a.first_name ?? ""}. I need: ${a.need ?? ""}`;
      card(`<b>Talk to the team</b> Need: ${esc(a.need)}
        <a href="https://wa.me/YOURNUMBER?text=${encodeURIComponent(msg)}" target="_blank">WhatsApp</a>`);
      conversation.sendToolResult(call.callId, { shown: "contact options" });
    } else {
      conversation.sendToolResult(call.callId, { ok: false, why: "unknown_service" });
    }
  });
 
  try { setStatus("Connecting…"); await conversation.connect(); }
  catch (err) { setStatus("Failed: " + (err.message ?? err)); conversation = null; }
};
 
$("hang-up").onclick = async () => { await conversation?.disconnect(); conversation = null; };

The parts that are easy to get wrong:

  • The persona never speaks first. Send response.create on avatar-presented, or the visitor sees a silent face.
  • Start from a click. Browsers play audio only after the person has interacted with the page, so connect() belongs in the button handler.
  • Answer every tool call. A call waits for its result as long as the session lasts. A result with ok: false tells the backend the call failed, and the persona tells the visitor.
  • Escape what the tools send you. The backend fills the arguments from what the visitor said, so treat them as user input. The esc function above keeps a name like <script> from becoming HTML.

Step 6: Run It

node server.mjs
# Nuance demo on http://localhost:5177

Open http://localhost:5177, allow the microphone, press Start call, and wait for the host to appear. That takes from a few seconds to about half a minute. Then talk to it.

In our test, the visitor said they run a logistics company in Riyadh whose team answers the same WhatsApp questions all day. The host answered: "Let me put our AI support agents on your screen, they answer customers on WhatsApp and email so your team doesn't have to repeat themselves." The service card appeared as she said it. When the visitor gave the name Karim and asked to talk to the team, she said "Bringing up the contact options for you now", and the contact card appeared with the name and need filled in.

Step 7: Test Without Talking

For repeatable tests, you can type the visitor's words instead of speaking them. Under responses delegation, send a user message and then ask for a reply:

await conversation.sendInterfaceEvent({
  type: "response.item.create",
  item: {
    type: "message",
    role: "user",
    content: [{ type: "input_text", text: "I run a logistics company in Riyadh. What can you do?" }],
  },
});
await conversation.sendInterfaceEvent({ type: "response.create" });

We ran our test call this way, with the speakers muted and a silent microphone, so the test played no sound in the office. Typed words do not appear in the input transcript events, so log them yourself if you want them in the record.

The Limits We Hit

These come from our own test on 20 November 2026 and from the official documentation. Check them again before you plan around them, since the API is new and versions below 1.0 can change.

English only. The persona speaks and hears English only. The check that reviews your prompt at mint time is strict: our first prompt said our websites are "built in Arabic, French and English", and the mint was refused with 400 instructions_refused: "Your system prompt asks the persona to speak Arabic." Text in another script is refused too. For a company whose visitors write in Arabic and French, that limits where it can go today.

Three faces. The API offers sam, sonia and mira. An unknown persona_id returns unknown_persona with that list. There is no upload of your own face, and API sessions cannot switch identity. You choose the name, role and manner in the prompt; the look and voice stay as they are. The video also carries a small watermark.

Topics the platform refuses. Prompts that ask for legal, tax or financial advice, medical guidance, religious guidance, political persuasion, or collection of sensitive data such as card numbers are refused at mint. Spoken card numbers and one-time codes arrive as [redacted] in transcripts.

Credits and concurrency. On our plan: 60 credits a day, one conversation at a time, and about 6 credits for a 90-second call. A second visitor who presses the button during a call gets a 409 concurrency_limit. A public button needs a "the host is busy, leave a message" fallback.

Troubleshooting

SymptomLikely causeFix
400 instructions_refused at mintThe prompt mentions another language or a refused topicRemove the line the detail names
The face appears but says nothingNo response.create after avatar-presentedSend it, as in Step 5
No soundThe call did not start from a clickCall connect() inside the click handler
A tool never firesTools at the top level, or not named in the promptPut them in delegation.responses.tools, name them in the prompt, read warnings
409 concurrency_limitAnother call is still runningHang up, or end it from the server with the end-conversation route
429 start_limitToo many tokens minted in the last hourMint on click, not on page load

Where It Fits on a Business Website

The useful version is not a novelty face on the home page. It is a host on a page where visitors already have a clear problem, with one job: understand the problem, show the matching service, and hand over a contact that already carries the visitor's need. Measure it with one number, how many calls end with the visitor pressing the contact button, and compare it to the same page without the host.

With English only, the honest place to try it is an English page for international buyers. For Arabic and French visitors, keep the text and WhatsApp routes you already have until the platform supports those languages.

Next Steps

  • Read our LiveKit and Next.js real-time video tutorial to understand the media room under the SDK.
  • Add a third tool that checks a calendar and offers two meeting times.
  • Save each call's transcript from the server (GET transcript route, after the call ends) and attach it to the contact record in your CRM.

Conclusion

In one evening and two files we had a live video host that understands a visitor's problem, shows the matching service, and hands over a prefilled contact. The hard parts were not the code. They were the limits: English only, three faces, a strict prompt review, and a small daily allowance of credits.

Want an AI host or a WhatsApp agent that brings real contacts to your website, in the languages your customers use? Talk to the Noqta team.

Send us your project

We reply within one working day.