Como Adicionar um Personagem de IA que Fala ao Seu Site
Adicione um personagem de IA falante a qualquer site: instale o Neocortex Web SDK, mantenha a chave de API no seu servidor, coloque um elemento de chat com voz e trate as ações.
Sercan AltundasFounder of Neocortex
· 7 min de leitura

Um personagem de site é um guia, um anfitrião ou um assistente de loja com quem os visitantes podem conversar com as próprias palavras, com personalidade e voz, em vez de uma bolha de chat genérica. Este guia mostra como adicionar um a qualquer site com o Neocortex Web SDK: algumas linhas no servidor, um elemento na página e ações opcionais para o personagem fazer coisas.
O que você vai construir
Um personagem na sua página que:
- responde perguntas digitadas ou faladas com a própria voz
- conhece o seu conteúdo, a partir de uma base de conhecimento que você envia
- pode executar ações na página, como abrir um produto ou iniciar um tour
- nunca expõe a sua chave de API para o navegador
O que você precisa
- Uma conta Neocortex, uma chave de API e um personagem criado no painel
- Um servidor que rode Node 20 ou posterior, ou Cloudflare Workers, Bun ou Deno
- Uma página servida por HTTPS, já que os navegadores só liberam o microfone em páginas seguras
Passo 1: crie o personagem
No editor do Neocortex, dê ao personagem uma personalidade, uma voz e uma base de conhecimento com as páginas de produto, as perguntas frequentes ou as notas do tour. Teste no navegador até ele soar certo: o teste no editor está incluído em todos os planos. Copie o id do personagem no painel.
Passo 2: instale o SDK
Execute npm install @neocortex-link/web no projeto do seu site.
Passo 3: adicione o proxy ao seu servidor
As chaves de API do Neocortex são secretas. Qualquer pessoa que leia uma chave no JavaScript da sua página pode aumentar o uso da sua conta, então o SDK traz um pequeno handler de servidor que guarda a chave. Ele também verifica quem está falando e só permite os personagens que você listar.
Em um app Next.js, crie 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 };O authorize devolve o visitante como { id }, ou null para recusar. Esse id vira o playerId do personagem, então cada visitante tem a própria conversa. Para Express, envolva o mesmo handler em toNodeHandler e monte-o em /api/neocortex. Sites sem login podem emitir para cada visitante um id estável em um cookie assinado.
Passo 4: coloque o personagem na página
Carregue a interface uma vez com import "@neocortex-link/web/ui/auto" (ou por uma tag de script de CDN, se o seu site não usar bundler), depois coloque o elemento onde o personagem deve aparecer:
<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>O chat traz uma caixa de texto e entrada de microfone. O atributo voice acrescenta respostas faladas: cada fala é transmitida como áudio, e a próxima é buscada enquanto a atual toca. Adicione push-to-talk se os visitantes devem segurar o botão para falar, ou mic="false" para apenas texto.
Os elementos são Web Components padrão, então funcionam com React, Vue, Svelte, Angular ou HTML puro, e você pode mudar o estilo com propriedades CSS customizadas, no modo claro ou escuro. Também há elementos para um chat em grupo com vários personagens (planos Pro e Team) e um apresentador de quiz (plano Team).
Passo 5: deixe o personagem agir
Defina ações no editor, como OPEN_PRODUCT ou START_TOUR, e depois trate-as na página:
const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));openProduct é uma função sua. O personagem decide quando uma ação combina com a conversa, e o seu código decide o que ela faz.
Ideias de personagens para sites
- Um guia de produto em um configurador 3D que explica as opções e troca as cores quando pedido.
- Um anfitrião de evento que responde a perguntas sobre a programação e indica aos visitantes o palco certo.
- Um personagem de museu ou de marca que conta histórias do seu acervo com a própria voz.
- A página de lançamento de um jogo, onde os visitantes podem conversar com os personagens do jogo antes de comprar.
Nossos guias de casos de uso cobrem em mais profundidade guias de compras com IA para lojas 3D na web e anfitriões com IA para eventos virtuais.
Problemas comuns
- O microfone não inicia. Os navegadores exigem HTTPS e um clique ou toque antes de gravar. Teste no seu domínio real, e não em uma prévia HTTP simples.
- 401 ou 403 do endpoint. O
authorizedevolveunull, ou o id do personagem não está na listacharacters. - A chave acabou no navegador. Nunca a passe para o código do cliente. Só o handler do servidor deve ler
NEOCORTEX_API_KEY.
Próximos passos
Para motores de jogo em vez de sites, comece por como adicionar um personagem de IA ao seu jogo na Unity. Para entender o lado da voz, leia como funciona o pipeline de voz de NPCs com IA. Todos os tutoriais da série estão no guia para criar NPCs com IA, e a configuração completa está na documentação do Web SDK.
Perguntas frequentes
Como adiciono um personagem de IA com voz ao meu site?
Instale o Neocortex Web SDK, adicione o pequeno proxy ao seu servidor para que a chave de API continue privada, e depois coloque um elemento neocortex-chat na página com o atributo voice. Os visitantes podem digitar ou falar, e o personagem responde em voz alta.
Posso colocar um chatbot de IA no meu site sem expor a minha chave de API?
Sim. O Neocortex Web SDK inclui um handler de servidor que guarda a chave, verifica quem está falando e permite apenas os personagens que você listar. O navegador só se comunica com o seu próprio endpoint.
Funciona com React, Vue ou WordPress?
A interface de chat é feita de Web Components padrão, então funciona com React, Vue, Svelte, Angular e HTML puro. Qualquer site que consiga rodar um pequeno endpoint de servidor, como Next.js, Express ou Cloudflare Workers, pode hospedar o proxy.
O Neocortex Web SDK é gratuito?
O SDK é código aberto sob a licença Apache-2.0. As conversas contam para o seu plano Neocortex.
O personagem pode fazer coisas na página?
Sim. Defina ações para o personagem no editor do Neocortex e registre um handler para cada uma na página, por exemplo para abrir um produto, iniciar um tour ou rolar até uma seção.






