V/LVer demo

Documentação técnica

Construa em cima da nossa API

Todas as rotas abaixo já existem e já funcionam em modo demo, sem precisar de credencial nenhuma. Configure as variáveis de ambiente quando quiser plugar um backend real.

Como funciona

A API roda com um princípio simples: sem endpoint externo configurado, todas as rotas respondem em modo demo, com dados coerentes pra você testar a integração antes de ligar qualquer coisa de verdade. Configure as variáveis abaixo em .env.local pra apontar pra um backend real:

FOUNDLAB_CONTEXT_API_URL=
FOUNDLAB_ONBOARDING_API_URL=
FOUNDLAB_VOICE_API_URL=
FOUNDLAB_API_KEY=

A chave de API nunca é exposta ao navegador. Ela só é usada nas rotas do lado do servidor, que repassam a chamada pro backend configurado.

Provedor de voz, não amarrado a um fornecedor só

Por trás da rota de sessão existe uma interface comum de provedor de voz. Hoje ela roda em modo demo por padrão; quando uma credencial real (Grok ou Gemini) for configurada, o provedor certo entra sem precisar mudar nenhuma outra parte do sistema. Nenhuma rota fala diretamente com um SDK de fornecedor específico.

Endpoints

GET/api/health

Status do serviço e quais integrações estão configuradas.

Resposta

{
  "service": "foundlab-voice-agents",
  "status": "ok",
  "mode": "local-compatible",
  "integrations": { "context": false, "onboarding": false, "voice": false },
  "timestamp": "2026-07-27T12:00:00.000Z"
}
POST/api/agent-context

Analisa a URL de um site e devolve contexto pra configurar o agente.

Corpo da requisição

{ "websiteUrl": "https://suaempresa.com.br" }

Resposta

{ "ok": true, "mode": "demo", "context": { ... } }
POST/api/onboarding

Cria um agente a partir de um template (ex: sales-associate).

Corpo da requisição

{ "websiteUrl": "https://suaempresa.com.br", "template": "sales-associate" }

Resposta

{ "ok": true, "mode": "demo", "agent": { ... } }
POST/api/voice/session

Inicia uma sessão de voz. Sem backend configurado, roda em modo demo e já registra o início da sessão.

Corpo da requisição

{ "agentTemplate": "sales-associate", "websiteUrl": "https://suaempresa.com.br" }

Resposta

{ "ok": true, "mode": "demo", "sessionId": "demo-...", "action": "dial" }
POST/api/voice/outcome

Registra o resultado de uma ação (tool call) executada pelo agente durante a sessão.

Corpo da requisição

{
  "sessionId": "demo-...",
  "toolName": "lead.qualify",
  "input": { "empresa": "..." },
  "output": { "qualified": true },
  "status": "success"
}

Resposta

{ "ok": true, "mode": "demo", "persisted": false, "reason": "..." }

Exemplo rápido

Registrar o resultado de uma ação, via curl:

curl -X POST https://SEU-DOMINIO/api/voice/outcome \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "demo-123",
    "toolName": "lead.qualify",
    "input": { "empresa": "Acme" },
    "output": { "qualified": true },
    "status": "success"
  }'