How to Add a Talking AI Character to Your Website

A website character is a guide, a host or a shop assistant that visitors can talk to in their own words, with a personality and a voice instead of a generic chat bubble. This guide shows how to add one to any site with the Neocortex Web SDK: a few lines on the server, one element on the page, and optional actions that let the character do things.

What you'll build

A character on your page that:

• answers typed or spoken questions in its own voice
• knows your content, from a knowledge base you upload
• can run actions on the page, like opening a product or starting a tour
• never exposes your API key to the browser

What you need

• A free Neocortex account, an API key and a character from the dashboard
• A server that runs Node 20 or later, or Cloudflare Workers, Bun or Deno
• A page served over HTTPS, since browsers only allow the microphone on secure pages

Step 1: design the character

In the Neocortex editor, give the character a personality, a voice and a knowledge base with your product pages, FAQs or tour notes. Test it in the browser until it sounds right: free in-editor testing is included on every plan. Copy the character's id from the dashboard.

Step 2: install the SDK

Run npm install @neocortex-link/web in your site's project.

Step 3: add the proxy to your server

Neocortex API keys are secret. Anyone who reads a key from your page's JavaScript can run up usage on your account, so the SDK ships a small server handler that holds the key. It also checks who is talking and only allows the characters you list.

In a Next.js app, create 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 returns the visitor as { id }, or null to refuse. That id becomes the character's playerId, so each visitor gets their own conversation. For Express, wrap the same handler in toNodeHandler and mount it at /api/neocortex. Sites without logins can issue each visitor a stable id in a signed cookie.

Step 4: drop the character on the page

Load the UI once with import "@neocortex-link/web/ui/auto" (or from a CDN script tag if your site has no bundler), then place the element wherever the character should appear:

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

The chat comes with a text box and microphone input. The voice attribute adds spoken replies: each line is streamed as speech, and the next line is fetched while the current one plays. Add push-to-talk if visitors should hold the button while speaking, or mic="false" for text only.

The elements are standard Web Components, so they work in React, Vue, Svelte, Angular or plain HTML, and you can restyle them with CSS custom properties in light or dark mode. There are also elements for a group chat with several characters (Pro and Team plans) and a quiz host (Team plan).

Step 5: let the character act

Define actions in the editor, such as OPEN_PRODUCT or START_TOUR, then handle them in the page:

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

openProduct is your own function. The character decides when an action fits the conversation, and your code decides what it does.

Ideas for website characters

• A product guide in a 3D configurator who explains options and switches colours when asked.
• An event host who answers schedule questions and points visitors to the right stage.
• A museum or brand character who tells stories from your archive in their own voice.
• A game's landing page where visitors can talk to the game's characters before they buy.

Our use-case guides cover AI shopping guides for 3D web stores and AI hosts for virtual events in more depth.

Common problems

• The microphone doesn't start. Browsers require HTTPS and a click or tap before recording. Test on your real domain, not a plain-HTTP preview.
• 401 or 403 from the endpoint. authorize returned null, or the character id isn't in the characters list.
• The key ended up in the browser. Never pass it to client code. Only the server handler should read NEOCORTEX_API_KEY.

Next steps

For game engines instead of websites, start with how to add an AI character to your Unity game. To understand the voice side, read how the AI NPC voice pipeline works. Every tutorial in the series is in the guide to building AI NPCs, and the full setup is in the Web SDK docs.

Frequently Asked Questions