écrits/tutorial/2026/11
● Tutorial20 nov. 2026·16 min

Créer un hôte vidéo IA en direct pour votre site web avec Nuance Live

Nous avons construit en une soirée un hôte vidéo IA qui parle, pour noqta.tn, avec l'API Nuance Live : un serveur de jetons, une page qui gère l'appel, et deux outils qui affichent une fiche de service et des options de contact préremplies sur l'écran du visiteur. Voici le code complet, ce que cela a coûté et les limites que nous avons rencontrées.

Un visiteur arrive sur une page de services, appuie sur un bouton, et une personne en vidéo lui dit bonjour, lui demande ce que fait son entreprise, puis affiche le bon service sur son écran tout en continuant à parler. Quand le visiteur veut parler à l'équipe, l'hôte lui demande son prénom et son besoin, puis affiche un bouton WhatsApp avec le message déjà rédigé.

C'est ce que nous avons construit pour noqta.tn le 20 novembre 2026 avec Nuance Live, une nouvelle API temps réel de Nuance Labs pour des personas IA qui parlent en vidéo en direct. Ce tutoriel vous donne le code complet et fonctionnel, le coût d'un appel, et les limites qui déterminent où cet outil peut, ou ne peut pas, être utilisé sur un vrai site.

Ce que vous allez construire

  • Un petit serveur Node.js qui garde votre clé API secrète et génère un jeton de session à usage unique pour chaque appel.
  • Une page web qui lance l'appel, affiche la vidéo du persona et écrit une transcription en direct.
  • Un prompt d'hôte qui fait du persona l'hôte d'accueil de votre entreprise.
  • Deux outils que le persona peut utiliser pendant qu'il parle : show_service affiche une fiche de service à l'écran, et show_contact affiche des options de contact avec le prénom et le besoin du visiteur déjà remplis.

Le tout tient en deux fichiers, sans étape de build. Le code complet est sur GitHub : nooqta/nuance-live-ai-host-demo.

Prérequis

  • Node.js 18 ou plus récent (le serveur utilise le fetch intégré).
  • Un compte Nuance Labs et une clé API obtenue depuis le tableau de bord. Les clés commencent par nk_.
  • Un navigateur sur localhost ou en https. Les navigateurs n'accordent le microphone à une page que dans un contexte sécurisé.
  • Des bases en JavaScript. Connaître WebRTC aide mais n'est pas obligatoire : le SDK gère la salle média pour vous.

Comment fonctionne Nuance Live

Nuance Live fait tourner la conversation dans une salle média LiveKit. Votre code fait trois choses :

  1. Votre serveur appelle POST https://api.nuancelabs.ai/session-tokens avec la clé API. Le jeton fixe tout ce qui concerne l'appel : le visage du persona, son prompt et ses outils. Il démarre une seule conversation, dans un délai de 60 secondes.
  2. Votre page transmet ce jeton au SDK JavaScript @nuancelabs/js-sdk, qui crée la conversation, attend que le persona soit prêt (jusqu'à environ une demi-minute), rejoint la salle et active le microphone.
  3. Pendant l'appel, les événements circulent dans les deux sens sur un canal de données : les transcriptions et les appels d'outils arrivent, et votre page renvoie des instructions, des messages tapés et les résultats des outils.

La clé API n'atteint jamais le navigateur. Si c'était le cas, n'importe qui pourrait lancer des appels sur vos crédits.

Étape 1 : vérifier votre forfait avant d'écrire du code

Votre forfait fixe trois chiffres qui orientent la conception. Consultez-les avec votre clé :

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

Avec notre clé, le 20 novembre 2026, la réponse était :

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

Donc : un seul appel à la fois, 60 crédits par jour, et 60 démarrages par heure. Notre appel de test d'environ une minute et demie, avec deux prises de parole du visiteur et les deux outils utilisés, a consommé 6 crédits. C'est suffisant pour une démo et quelques appels commerciaux par jour. Ce n'est pas suffisant pour un bouton ouvert à tous sur une page très fréquentée. Prévoyez-le avant de le mettre devant le public.

Étape 2 : préparer le projet

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

Gardez .env hors de git. Le serveur le lit au démarrage, donc aucun paquet n'est nécessaire.

Étape 3 : écrire le prompt de l'hôte

Le prompt du persona est personality.system_prompt. Rédigez-le comme le briefing d'une personne qui répond au téléphone : qui elle est, ce qu'elle fait, ce qu'elle ne doit pas faire, et quand utiliser chaque outil.

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.`;

Trois lignes y comptent plus qu'il n'y paraît :

  • "Say 'Let me put that on your screen', not 'it's there'." (Dites « Je vous affiche cela à l'écran », et non « c'est affiché ».) Le persona parle avant que votre outil ne s'exécute. S'il dit « c'est fait », il le dit avant que quoi que ce soit ne soit fait.
  • "You don't know prices." (Vous ne connaissez pas les prix.) Sans cette ligne, un modèle vocal inventera un prix pour se montrer utile. Un prix inventé sur votre propre site est pire qu'une absence de réponse.
  • "You do not give tax, legal or financial advice." (Vous ne donnez pas de conseils fiscaux, juridiques ou financiers.) La plateforme refuse les prompts qui demandent ce type de conseil, et c'est de toute façon la bonne règle pour un hôte commercial.

Astuce : le persona n'a pas de nom tant que le prompt ne lui en donne pas un. persona_id choisit uniquement le visage et la voix.

Étape 4 : écrire le serveur de jetons

Le serveur remplit quatre fonctions : servir la page, générer un jeton, afficher vos crédits restants et lister les services pour la page. Enregistrez-le sous 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}`));

Ce que fait chaque paramètre :

  • delegation.type: "responses" place un moteur de raisonnement côté serveur derrière le persona. Quand le persona délègue une tâche, ce backend décide lequel de vos outils appeler et avec quels arguments. Votre page exécute l'outil et renvoie le résultat.
  • tools doit se trouver à l'intérieur de delegation.responses. Les outils placés au premier niveau du corps de la requête sont ignorés, et le champ warnings de la réponse le signale. Lisez warnings à chaque génération de jeton : c'est le seul endroit où un outil ignoré est signalé.
  • video.input.camera: false empêche le persona d'utiliser la caméra du visiteur. Un hôte commercial n'a pas besoin de voir le visiteur, et moins de demandes d'autorisation signifie que plus de visiteurs restent.
  • runtime_tools.end_call: true permet au persona de raccrocher après avoir dit au revoir.
  • end_user_id est votre identifiant pour la personne. Hachez d'abord toute donnée personnelle. Pour la démo, nous hachons l'adresse IP ; sur un vrai site, utilisez votre propre identifiant de session.

Étape 5 : construire la page

Enregistrez ceci sous index.html, à côté du serveur. Les styles sont omis ici pour garder le code court ; n'importe quelle mise en page avec une vidéo, une zone de fiches et une transcription fonctionne.

<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; };

Les points sur lesquels on se trompe facilement :

  • Le persona ne parle jamais en premier. Envoyez response.create sur avatar-presented, sinon le visiteur voit un visage muet.
  • Démarrez à partir d'un clic. Les navigateurs ne jouent du son qu'après une interaction de la personne avec la page, donc connect() doit se trouver dans le gestionnaire du bouton.
  • Répondez à chaque appel d'outil. Un appel attend son résultat tant que la session dure. Un résultat avec ok: false indique au backend que l'appel a échoué, et le persona le dit au visiteur.
  • Échappez ce que les outils vous envoient. Le backend remplit les arguments à partir de ce que le visiteur a dit, donc traitez-les comme une saisie utilisateur. La fonction esc ci-dessus empêche un nom comme <script> de devenir du HTML.

Étape 6 : lancer le projet

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

Ouvrez http://localhost:5177, autorisez le microphone, appuyez sur Start call et attendez que l'hôte apparaisse. Cela prend de quelques secondes à environ une demi-minute. Ensuite, parlez-lui.

Lors de notre test, le visiteur a expliqué qu'il dirige une entreprise de logistique à Riyad dont l'équipe répond toute la journée aux mêmes questions sur WhatsApp. L'hôte a répondu : "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." (Je vous affiche nos agents de support IA, ils répondent aux clients sur WhatsApp et par e-mail pour que votre équipe n'ait pas à se répéter.) La fiche de service est apparue au moment où elle le disait. Quand le visiteur a donné le prénom Karim et demandé à parler à l'équipe, elle a dit "Bringing up the contact options for you now" (J'affiche les options de contact pour vous), et la fiche de contact est apparue avec le prénom et le besoin déjà remplis.

Étape 7 : tester sans parler

Pour des tests reproductibles, vous pouvez taper les paroles du visiteur au lieu de les prononcer. Avec la délégation responses, envoyez un message utilisateur puis demandez une réponse :

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" });

Nous avons réalisé notre appel de test de cette façon, haut-parleurs coupés et microphone silencieux, pour que le test ne fasse aucun bruit au bureau. Les mots tapés n'apparaissent pas dans les événements de transcription d'entrée, donc enregistrez-les vous-même si vous voulez les garder dans l'historique.

Les limites que nous avons rencontrées

Elles proviennent de notre propre test du 20 novembre 2026 et de la documentation officielle. Vérifiez-les de nouveau avant de bâtir votre projet autour, car l'API est récente et les versions antérieures à la 1.0 peuvent changer.

Anglais uniquement. Le persona parle et comprend uniquement l'anglais. La vérification qui examine votre prompt lors de la génération du jeton est stricte : notre premier prompt indiquait que nos sites sont "built in Arabic, French and English" (construits en arabe, en français et en anglais), et la génération a été refusée avec 400 instructions_refused : "Your system prompt asks the persona to speak Arabic." (Votre prompt système demande au persona de parler arabe.) Un texte dans une autre écriture est également refusé. Pour une entreprise dont les visiteurs écrivent en arabe et en français, cela limite aujourd'hui les endroits où l'utiliser.

Trois visages. L'API propose sam, sonia et mira. Un persona_id inconnu renvoie unknown_persona avec cette liste. Il n'est pas possible de téléverser votre propre visage, et les sessions API ne peuvent pas changer d'identité. Vous choisissez le nom, le rôle et le ton dans le prompt ; l'apparence et la voix restent telles quelles. La vidéo porte aussi un petit filigrane.

Sujets refusés par la plateforme. Les prompts qui demandent des conseils juridiques, fiscaux ou financiers, des conseils médicaux, des conseils religieux, de la persuasion politique, ou la collecte de données sensibles comme des numéros de carte sont refusés lors de la génération du jeton. Les numéros de carte et les codes à usage unique prononcés à voix haute arrivent sous la forme [redacted] dans les transcriptions.

Crédits et simultanéité. Avec notre forfait : 60 crédits par jour, une seule conversation à la fois, et environ 6 crédits pour un appel de 90 secondes. Un second visiteur qui appuie sur le bouton pendant un appel reçoit une erreur 409 concurrency_limit. Un bouton public a besoin d'une solution de repli du type « l'hôte est occupé, laissez un message ».

Dépannage

SymptômeCause probableSolution
400 instructions_refused lors de la génération du jetonLe prompt mentionne une autre langue ou un sujet refuséSupprimez la ligne indiquée dans detail
Le visage apparaît mais ne dit rienPas de response.create après avatar-presentedEnvoyez-le, comme à l'étape 5
Pas de sonL'appel n'a pas démarré à partir d'un clicAppelez connect() dans le gestionnaire de clic
Un outil ne se déclenche jamaisOutils placés au premier niveau, ou non nommés dans le promptPlacez-les dans delegation.responses.tools, nommez-les dans le prompt, lisez warnings
409 concurrency_limitUn autre appel est encore en coursRaccrochez, ou terminez-le depuis le serveur avec la route de fin de conversation
429 start_limitTrop de jetons générés au cours de la dernière heureGénérez le jeton au clic, pas au chargement de la page

Sa place sur un site d'entreprise

La version utile n'est pas un visage gadget sur la page d'accueil. C'est un hôte placé sur une page où les visiteurs ont déjà un problème précis, avec une seule mission : comprendre le problème, afficher le service correspondant, et transmettre un contact qui contient déjà le besoin du visiteur. Mesurez-le avec un seul chiffre, le nombre d'appels qui se terminent par un clic du visiteur sur le bouton de contact, et comparez-le à la même page sans l'hôte.

Comme l'outil ne fonctionne qu'en anglais, l'endroit honnête pour l'essayer est une page en anglais destinée aux acheteurs internationaux. Pour les visiteurs arabophones et francophones, gardez les canaux texte et WhatsApp que vous avez déjà, jusqu'à ce que la plateforme prenne en charge ces langues.

Prochaines étapes

  • Lisez notre tutoriel sur la vidéo en temps réel avec LiveKit et Next.js pour comprendre la salle média qui se trouve sous le SDK.
  • Ajoutez un troisième outil qui consulte un agenda et propose deux créneaux de rendez-vous.
  • Enregistrez la transcription de chaque appel depuis le serveur (route GET de transcription, une fois l'appel terminé) et rattachez-la à la fiche du contact dans votre CRM.

Conclusion

En une soirée et deux fichiers, nous avions un hôte vidéo en direct qui comprend le problème d'un visiteur, affiche le service correspondant et transmet un contact prérempli. Le plus difficile n'était pas le code, mais les limites : anglais uniquement, trois visages, un examen strict du prompt et un petit quota quotidien de crédits.

Vous voulez un hôte IA ou un agent WhatsApp qui apporte de vrais contacts à votre site web, dans les langues de vos clients ? Parlez à l'équipe Noqta.

Envoyez-nous votre projet

Nous répondons sous un jour ouvré.