Neocortex Logo

Comment ajouter un personnage IA qui parle à votre site

Ajoutez un personnage IA qui parle à n'importe quel site : installez le SDK Web de Neocortex, gardez la clé API sur votre serveur, insérez un élément de chat vocal et gérez les actions.

Sercan AltundasFounder of Neocortex

· 7 min de lecture

Ajoutez un personnage IA qui parle à n'importe quel site : installez le SDK Web de Neocortex, gardez la clé API sur votre serveur, insérez un élément de chat vocal et gérez les actions.

Un personnage de site est un guide, un hôte ou un assistant de boutique à qui les visiteurs peuvent parler avec leurs propres mots, doté d'une personnalité et d'une voix au lieu d'une simple bulle de chat générique. Ce guide montre comment en ajouter un à n'importe quel site avec le SDK Web de Neocortex : quelques lignes côté serveur, un élément sur la page, et des actions facultatives qui permettent au personnage de faire des choses.

Ce que vous allez construire

Un personnage sur votre page qui :

  • répond aux questions tapées ou prononcées avec sa propre voix
  • connaît votre contenu, grâce à une base de connaissances que vous téléversez
  • peut lancer des actions sur la page, comme ouvrir un produit ou démarrer une visite guidée
  • n'expose jamais votre clé API au navigateur

Ce qu'il vous faut

  • Un compte Neocortex, une clé API et un personnage depuis le tableau de bord
  • Un serveur qui fait tourner Node 20 ou plus récent, ou Cloudflare Workers, Bun ou Deno
  • Une page servie en HTTPS, car les navigateurs n'autorisent le micro que sur les pages sécurisées

Étape 1 : concevoir le personnage

Dans l'éditeur Neocortex, donnez au personnage une personnalité, une voix et une base de connaissances avec les pages de vos produits, vos FAQ ou les notes de vos visites guidées. Testez-le dans le navigateur jusqu'à ce qu'il sonne juste : le test dans l'éditeur est inclus dans chaque forfait. Copiez l'identifiant du personnage depuis le tableau de bord.

Étape 2 : installer le SDK

Exécutez npm install @neocortex-link/web dans le projet de votre site.

Étape 3 : ajouter le proxy à votre serveur

Les clés API Neocortex sont secrètes. Quiconque lit une clé dans le JavaScript de votre page peut faire grimper l'usage sur votre compte, donc le SDK fournit un petit gestionnaire serveur qui garde la clé. Il vérifie aussi qui parle et n'autorise que les personnages que vous listez.

Dans une application Next.js, créez app/api/neocortex/[...path]/route.ts :

import { createNeocortexHandler } from "@neocortex-link/web/server";
import { auth } from "@/auth";

const handler = createNeocortexHandler({
  apiKey: process.env.NEOCORTEX_API_KEY!,
  characters: ["your-character-id"],
  authorize: async () => {
    const session = await auth();
    return session?.user ? { id: session.user.id } : null;
  },
});

export { handler as GET, handler as POST, handler as OPTIONS };

authorize renvoie le visiteur sous la forme { id }, ou null pour refuser. Cet identifiant devient le playerId du personnage, donc chaque visiteur a sa propre conversation. Pour Express, enveloppez le même gestionnaire dans toNodeHandler et montez-le sur /api/neocortex. Les sites sans connexion peuvent attribuer à chaque visiteur un identifiant stable dans un cookie signé.

Étape 4 : placer le personnage sur la page

Chargez l'interface une seule fois avec import "@neocortex-link/web/ui/auto" (ou depuis une balise script CDN si votre site n'a pas de bundler), puis placez l'élément là où le personnage doit apparaître :

<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>

Le chat comprend une zone de texte et une entrée micro. L'attribut voice ajoute des réponses parlées : chaque réplique est diffusée en voix, et la suivante est récupérée pendant que la courante se joue. Ajoutez push-to-talk si les visiteurs doivent maintenir le bouton pour parler, ou mic="false" pour le texte seul.

Les éléments sont des Web Components standard, ils fonctionnent donc avec React, Vue, Svelte, Angular ou du HTML simple, et vous pouvez les restyler avec des propriétés CSS personnalisées en mode clair ou sombre. Il existe aussi des éléments pour un chat de groupe avec plusieurs personnages (forfaits Pro et Team) et un animateur de quiz (forfait Team).

Étape 5 : laisser le personnage agir

Définissez des actions dans l'éditeur, comme OPEN_PRODUCT ou START_TOUR, puis gérez-les dans la page :

const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));

openProduct est votre propre fonction. Le personnage décide quand une action convient à la conversation, et votre code décide de ce qu'elle fait.

Idées de personnages pour site

  • Un guide produit dans un configurateur 3D qui explique les options et change les couleurs sur demande.
  • Un animateur d'événement qui répond aux questions sur le programme et oriente les visiteurs vers la bonne scène.
  • Un personnage de musée ou de marque qui raconte des histoires tirées de vos archives avec sa propre voix.
  • La page d'accueil d'un jeu où les visiteurs peuvent parler aux personnages du jeu avant d'acheter.

Nos guides de cas d'usage couvrent plus en détail les guides d'achat IA pour boutiques web 3D et les animateurs IA pour événements virtuels.

Problèmes courants

  • Le micro ne démarre pas. Les navigateurs exigent HTTPS et un clic ou un toucher avant l'enregistrement. Testez sur votre domaine réel, et non sur un aperçu en HTTP simple.
  • Erreur 401 ou 403 depuis le point d'accès. authorize a renvoyé null, ou l'identifiant du personnage n'est pas dans la liste characters.
  • La clé s'est retrouvée dans le navigateur. Ne la transmettez jamais au code client. Seul le gestionnaire serveur doit lire NEOCORTEX_API_KEY.

Prochaines étapes

Pour des moteurs de jeu plutôt que des sites web, commencez par comment ajouter un personnage IA à votre jeu Unity. Pour comprendre le volet voix, lisez le fonctionnement du pipeline vocal des PNJ IA. Chaque tutoriel de la série se trouve dans le guide pour créer des PNJ IA, et la mise en place complète est dans la documentation du SDK Web.

Questions fréquentes

Comment ajouter un personnage IA avec voix à mon site ?

Installez le SDK Web de Neocortex, ajoutez son petit proxy à votre serveur pour que la clé API reste privée, puis placez un élément neocortex-chat sur la page avec l'attribut voice. Les visiteurs peuvent taper ou parler, et le personnage répond à voix haute.

Puis-je mettre un chatbot IA sur mon site sans exposer ma clé API ?

Oui. Le SDK Web de Neocortex comprend un gestionnaire serveur qui garde la clé, vérifie qui parle et n'autorise que les personnages que vous listez. Le navigateur ne parle jamais qu'à votre propre point d'accès.

Cela fonctionne-t-il avec React, Vue ou WordPress ?

L'interface de chat est faite de Web Components standard, elle fonctionne donc avec React, Vue, Svelte, Angular et le HTML simple. Tout site capable de faire tourner un petit point d'accès serveur, comme Next.js, Express ou Cloudflare Workers, peut héberger le proxy.

Le SDK Web de Neocortex est-il gratuit ?

Le SDK est open source sous licence Apache-2.0. Les conversations comptent dans le forfait Neocortex que vous utilisez.

Le personnage peut-il faire des choses sur la page ?

Oui. Définissez des actions pour le personnage dans l'éditeur Neocortex, puis enregistrez un gestionnaire pour chacune dans la page, par exemple pour ouvrir un produit, démarrer une visite guidée ou faire défiler jusqu'à une section.

Articles similaires

À lire aussi