Cómo añadir un personaje de IA que habla a tu web
Añade un personaje de IA que habla a cualquier web: instala el SDK web de Neocortex, mantén la clave de API en tu servidor, coloca un elemento de chat con voz y gestiona las acciones.
Sercan AltundasFounder of Neocortex
· 7 min de lectura

Un personaje de web es un guía, un anfitrión o un asistente de tienda con el que los visitantes pueden hablar con sus propias palabras, con personalidad y voz en lugar de una burbuja de chat genérica. Esta guía muestra cómo añadir uno a cualquier sitio con el SDK web de Neocortex: unas pocas líneas en el servidor, un elemento en la página y acciones opcionales que permiten al personaje hacer cosas.
Lo que vas a construir
Un personaje en tu página que:
- responde preguntas escritas o habladas con su propia voz
- conoce tu contenido, a partir de una base de conocimiento que subes
- puede ejecutar acciones en la página, como abrir un producto o iniciar un recorrido
- nunca expone tu clave de API al navegador
Lo que necesitas
- Una cuenta de Neocortex, una clave de API y un personaje del panel
- Un servidor que ejecute Node 20 o posterior, o Cloudflare Workers, Bun o Deno
- Una página servida por HTTPS, ya que los navegadores solo permiten el micrófono en páginas seguras
Paso 1: diseña el personaje
En el editor de Neocortex, dale al personaje una personalidad, una voz y una base de conocimiento con las páginas de tu producto, las preguntas frecuentes o las notas de tu recorrido. Pruébalo en el navegador hasta que suene bien: la prueba dentro del editor está incluida en todos los planes. Copia el ID del personaje desde el panel.
Paso 2: instala el SDK
Ejecuta npm install @neocortex-link/web en el proyecto de tu sitio.
Paso 3: añade el proxy a tu servidor
Las claves de API de Neocortex son secretas. Cualquiera que lea una clave desde el JavaScript de tu página puede disparar el consumo de tu cuenta, así que el SDK incluye un pequeño manejador de servidor que guarda la clave. Además, comprueba quién habla y solo permite los personajes que enumeres.
En una app de Next.js, crea 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 devuelve al visitante como { id }, o null para rechazarlo. Ese id se convierte en el playerId del personaje, así que cada visitante tiene su propia conversación. Para Express, envuelve el mismo manejador en toNodeHandler y móntalo en /api/neocortex. Los sitios sin inicio de sesión pueden asignar a cada visitante un id estable en una cookie firmada.
Paso 4: coloca el personaje en la página
Carga la interfaz una vez con import "@neocortex-link/web/ui/auto" (o desde una etiqueta script de CDN si tu sitio no usa bundler), y después coloca el elemento donde debe aparecer el personaje:
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>El chat incluye un cuadro de texto y entrada de micrófono. El atributo voice añade respuestas habladas: cada línea se transmite como voz, y la siguiente se pide mientras suena la actual. Añade push-to-talk si los visitantes deben mantener pulsado el botón al hablar, o mic="false" para solo texto.
Los elementos son Web Components estándar, así que funcionan en React, Vue, Svelte, Angular o HTML puro, y puedes cambiar su estilo con propiedades personalizadas de CSS en modo claro u oscuro. También hay elementos para un chat de grupo con varios personajes (planes Pro y Team) y un presentador de concursos (plan Team).
Paso 5: deja que el personaje actúe
Define acciones en el editor, como OPEN_PRODUCT o START_TOUR, y después gestiónalas en la página:
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct es tu propia función. El personaje decide cuándo una acción encaja con la conversación, y tu código decide qué hace.
Ideas para personajes de web
- Una guía de producto en un configurador 3D que explica las opciones y cambia los colores cuando se lo piden.
- Un anfitrión de evento que responde preguntas sobre el horario y señala a los visitantes el escenario correcto.
- Un personaje de museo o de marca que cuenta historias de tu archivo con su propia voz.
- La página de inicio de un juego en la que los visitantes pueden hablar con los personajes del juego antes de comprarlo.
Nuestras guías de casos de uso cubren con más detalle guías de compra con IA para tiendas web en 3D y anfitriones con IA para eventos virtuales.
Problemas habituales
- El micrófono no se activa. Los navegadores exigen HTTPS y un clic o toque antes de grabar. Prueba en tu dominio real, no en una vista previa con HTTP simple.
- 401 o 403 desde el endpoint.
authorizedevolviónull, o el ID del personaje no está en la listacharacters. - La clave acabó en el navegador. Nunca la pases al código del cliente. Solo el manejador del servidor debe leer
NEOCORTEX_API_KEY.
Próximos pasos
Si en lugar de una web quieres un motor de juego, empieza con cómo añadir un personaje de IA a tu juego de Unity. Para entender la parte de voz, lee cómo funciona la cadena de voz de los NPC con IA. Cada tutorial de la serie está en la guía para crear NPC con IA, y la configuración completa está en la documentación del SDK web.
Preguntas frecuentes
¿Cómo añado a mi web un personaje de IA con voz?
Instala el SDK web de Neocortex, añade su pequeño proxy a tu servidor para que la clave de API quede privada, y después coloca un elemento neocortex-chat en la página con el atributo voice. Los visitantes pueden escribir o hablar, y el personaje responde en voz alta.
¿Puedo poner un chatbot de IA en mi web sin exponer mi clave de API?
Sí. El SDK web de Neocortex incluye un manejador de servidor que guarda la clave, comprueba quién habla y solo permite los personajes que enumeres. El navegador solo habla con tu propio endpoint.
¿Funciona con React, Vue o WordPress?
La interfaz de chat está hecha de Web Components estándar, así que funciona en React, Vue, Svelte, Angular y HTML puro. Cualquier sitio que pueda ejecutar un pequeño endpoint de servidor, como Next.js, Express o Cloudflare Workers, puede alojar el proxy.
¿Es gratuito el SDK web de Neocortex?
El SDK es de código abierto con licencia Apache-2.0. Las conversaciones cuentan para tu plan de Neocortex.
¿Puede el personaje hacer cosas en la página?
Sí. Define acciones para el personaje en el editor de Neocortex, y después registra un manejador para cada una en la página, por ejemplo para abrir un producto, iniciar un recorrido o desplazarse a una sección.






