SDK Lite Web

Visão geral

O SDK @acertpix/voice-agent adiciona um agente de voz interativo à sua página. Ele pode ser usado de três formas:

Forma	Para quem	Arquivo
Web Component (`<acertpix-voice-agent>`)	HTML puro, qualquer framework	`voice-agent.*.umd.js`
Componente React (`<VoiceAgentWidget>`)	Projetos React com JSX	`voice-agent-react.*.umd.js`
Hook React (`useVoiceAgent`)	React avançado — UI personalizada	`voice-agent-react.*.esm.js`

Arquivos disponíveis

Os arquivos são servidos em https://sdk.skia.com.br/sdk/.

Arquivos versionados (estáveis, com SRI)

São permanentes — nunca removidos após publicados.

Versão de exemplo

Os números de versão abaixo (0.1.27183) são apenas ilustrativos. Consulte /sdk/sri-hashes.json para descobrir a versão atual, ou /sdk/sri-hashes-history.json para ver todas as versões disponíveis.

/sdk/voice-agent.0.1.27183.umd.js         ← Web Component (uso via <script>)
/sdk/voice-agent.0.1.27183.esm.js         ← Web Component (via import ESM)
/sdk/voice-agent-react.0.1.27183.umd.js   ← React wrapper (UMD)
/sdk/voice-agent-react.0.1.27183.esm.js   ← React wrapper (ESM)

Aliases sem versão (sempre o mais recente)

Sobrescritos a cada nova release. Use apenas em desenvolvimento.

/sdk/voice-agent.umd.js
/sdk/voice-agent.esm.js
/sdk/voice-agent-react.umd.js
/sdk/voice-agent-react.esm.js

Hashes SRI

SRI (Subresource Integrity) impede que um arquivo adulterado seja executado pelo browser. O hash SHA-384 do arquivo é declarado no HTML e verificado antes da execução.

Endpoints

URL	Descrição
`/sdk/sri-hashes.json`	Hashes da versão atual em JSON
`/sdk/sri-hashes.txt`	Snippets HTML prontos para copiar
`/sdk/sri-hashes-history.json`	Hashes de todas as versões publicadas

Formato de `/sdk/sri-hashes.json`

Hashes são únicos por arquivo

Os hashes abaixo são fictícios, mostrados apenas para ilustrar o formato. Sempre busque o valor real em /sdk/sri-hashes.json antes de incluir no seu HTML.

{
  "voice-agent.0.1.27183.umd.js": "sha384-da9qjXQlrq...",
  "voice-agent.0.1.27183.esm.js": "sha384-4p04XU9...",
  "voice-agent-react.0.1.27183.umd.js": "sha384-KMqhebPi...",
  "voice-agent-react.0.1.27183.esm.js": "sha384-EG8+jhXv..."
}

Opção 1 — Web Component (HTML puro)

A forma mais simples. Funciona em qualquer página HTML, WordPress, Webflow, ou qualquer framework.

Passo a passo para incluir com SRI

Acesse /sdk/sri-hashes.json e copie a versão atual e o hash do arquivo voice-agent.*.umd.js.
Substitua VERSAO e HASH_REAL_AQUI nos exemplos abaixo.

Inclusão com SRI (produção)

<script src="https://sdk.skia.com.br/sdk/voice-agent.0.1.VERSAO.umd.js"
        integrity="sha384-HASH_REAL_AQUI"
        crossorigin="anonymous"></script>

<acertpix-voice-agent
  sdk-key="sua-chave-aqui"
  backend-url="https://sdk.skia.com.br">
</acertpix-voice-agent>

### Exemplos de dimensionamento

Controle direto via atributos (fixo em px):

```html
<acertpix-voice-agent
  sdk-key="sua-chave"
  backend-url="https://sdk.skia.com.br"
  max-width="500px"
  avatar-height="230px"
  transcript-height="300px"
></acertpix-voice-agent>

Largura em percentual — relativa ao container pai:

<div style="width:80%">
  <acertpix-voice-agent
    sdk-key="sua-chave"
    backend-url="https://sdk.skia.com.br"
    max-width="100%"
    avatar-width="50%"
  ></acertpix-voice-agent>
</div>

Usando width/height diretamente (px, %, vh ou calc):

<acertpix-voice-agent
  sdk-key="sua-chave"
  width="420px"            <!-- largura fixa do host -->
  height="70vh"           <!-- altura total do widget -->
  transcript-height="calc(100% - 280px)"  <!-- painel de transcrição adaptável -->
></acertpix-voice-agent>

Override via CSS custom property (útil para integrações):

<acertpix-voice-agent
  sdk-key="sua-chave"
  style="--va-max-width:420px; --va-transcript-height:30vh; --va-avatar-width:100%"
></acertpix-voice-agent>

Notas rápidas:

width e max-width: width aplica a largura do :host diretamente; max-width continua disponível para comportamento responsivo.
avatar-width controla apenas a largura da área de vídeo do avatar (padrão 100%).
transcript-height controla a altura máxima do painel de transcrição; o conteúdo rola automaticamente quando excede essa altura.

### Inclusão sem SRI (desenvolvimento)

```html
<script src="https://sdk.skia.com.br/sdk/voice-agent.umd.js"></script>

<acertpix-voice-agent
  sdk-key="sua-chave-aqui"
  backend-url="https://sdk.skia.com.br">
</acertpix-voice-agent>

Atributos disponíveis

Atributo	Obrigatório	Padrão	Descrição
`sdk-key`	✅	—	Chave pública do seu projeto
`backend-url`	—	mesma origem	URL base do backend AcertPix
`show-avatar`	—	`"true"`	Exibe ou oculta o vídeo do avatar
`show-indicators`	—	`"true"`	Exibe ou oculta os indicadores de fala
`show-transcript`	—	`"true"`	Exibe ou oculta o painel de transcrição
`show-mute-button`	—	`"true"`	Exibe ou oculta o botão de mute
`theme`	—	`"dark"`	Preset visual: `"dark"` ou `"light"`
`width`	—	nenhuma (auto)	Largura fixa do widget (ex: `420px`). Se presente, sobrescreve o comportamento responsivo de `max-width`
`max-width`	—	`"480px"`	Largura máxima do widget
`avatar-width`	—	`100%`	Largura do vídeo do avatar; por padrão ocupa a largura do conteúdo do widget
`avatar-height`	—	`"260px"`	Altura da área de vídeo do avatar
`transcript-height`	—	`"200px"`	Altura máxima do painel de transcrição
`background-color`	—	`#0f0f0f`	Cor de fundo do widget
`surface-color`	—	`#1e1e1e`	Cor de cards internos (indicadores e mensagens do agente)
`border-color`	—	sem borda	Borda do widget (ex: `1px solid #ddd`)
`text-color`	—	`#f0f0f0`	Cor principal do texto
`primary-color`	—	`#2563eb`	Cor primária (botão iniciar e balão do usuário)
`danger-color`	—	`#dc2626`	Cor do botão de encerrar
`mute-idle-color`	—	`#374151`	Cor do botão de mute (normal)
`mute-active-color`	—	`#b45309`	Cor do botão de mute (quando mutado)
`indicator-user-color`	—	`#4ade80`	Cor das barrinhas do indicador do usuário
`indicator-agent-color`	—	`#60a5fa`	Cor das barrinhas do indicador do agente
`font-family`	—	`system-ui, sans-serif`	Fonte principal do widget
`labels`	—	textos padrão PT-BR	JSON com textos customizados (i18n)

Para ocultar um elemento, passe "false":

<!-- Só avatar e botão de mute, sem transcrição nem indicadores -->
<acertpix-voice-agent
  sdk-key="sua-chave"
  backend-url="https://sdk.skia.com.br"
  show-indicators="false"
  show-transcript="false">
</acertpix-voice-agent>

Exemplo com customização visual + labels:

<acertpix-voice-agent
  sdk-key="sua-chave"
  backend-url="https://sdk.skia.com.br"
  theme="light"
  width="420px"
  max-width="420px"
  avatar-width="100%"
  avatar-height="230px"
  primary-color="#0d9488"
  border-color="1px solid #d1d5db"
  labels='{"start":"Start","stop":"Stop","mute":"Mute","unmute":"Unmute"}'>
</acertpix-voice-agent>

Opção 2 — Componente React (`<VoiceAgentWidget>`)

Para projetos React. Inclui toda a UI pronta (avatar, controles, transcrição).

Passo a passo para incluir com SRI

Acesse /sdk/sri-hashes.json e copie a versão atual e o hash do arquivo voice-agent-react.*.umd.js.
Substitua VERSAO e HASH_REAL_AQUI abaixo.

Inclusão via UMD (CDN)

<script src="https://sdk.skia.com.br/sdk/voice-agent-react.0.1.VERSAO.umd.js"
        integrity="sha384-HASH_REAL_AQUI"
        crossorigin="anonymous"></script>

Uso básico

import VoiceAgentWidget from 'voice-agent-react'

export default function App() {
  return (
    <VoiceAgentWidget
      sdkKey="sua-chave-aqui"
      backendUrl="https://sdk.skia.com.br"
    />
  )
}

Props de UI

Prop	Tipo	Padrão	Descrição
`showAvatar`	`boolean`	`true`	Exibe ou oculta o vídeo do avatar
`showIndicators`	`boolean`	`true`	Exibe ou oculta os indicadores de fala
`showTranscript`	`boolean`	`true`	Exibe ou oculta o painel de transcrição
`showMuteButton`	`boolean`	`true`	Exibe ou oculta o botão de mute
`theme`	`VoiceAgentTheme`	`undefined`	Define preset (`dark`/`light`) e tokens visuais
`labels`	`VoiceAgentLabels`	`undefined`	Override dos textos da UI (i18n)

VoiceAgentTheme suporta: preset, maxWidth, avatarHeight, transcriptHeight, backgroundColor, surfaceColor, borderColor, textColor, primaryColor, dangerColor, muteIdleColor, muteActiveColor, indicatorUserColor, indicatorAgentColor, fontFamily.

VoiceAgentLabels suporta: start, stop, mute, unmute, connecting, connected, idle, error, busy, busyMessage, agentSpeaking, agentListening, emptyTranscript, userRole, agentRole.

Exemplo com React:

<VoiceAgentWidget
  sdkKey="sua-chave"
  backendUrl="https://sdk.skia.com.br"
  theme={{
    preset: 'light',
    primaryColor: '#0d9488',
    maxWidth: '420px',
    avatarHeight: '230px',
  }}
  labels={{
    start: 'Start Conversation',
    stop: 'Stop',
    mute: 'Mute',
    unmute: 'Unmute',
    userRole: 'You',
    agentRole: 'Agent',
  }}
/>

Props do agente

Prop	Tipo	Padrão	Descrição
`sdkKey`	`string`	obrigatório	Chave pública do projeto
`backendUrl`	`string`	mesma origem	URL base do backend AcertPix
`startMuted`	`boolean`	`false`	Inicia com microfone mutado
`vadThreshold`	`number`	`0.015`	Sensibilidade de detecção de voz (0–1)
`vadSilenceMs`	`number`	`700`	Tempo (ms) de silêncio para parar a detecção
`captureSampleRate`	`number`	`16000`	Sample rate do microfone (Hz)

Callbacks

Prop	Assinatura	Quando é chamado
`onStatus`	`(status: AgentStatus) => void`	Status muda: `idle` → `connecting` → `connected` → `busy` / `error`
`onTranscript`	`(entry: TranscriptEntry) => void`	Nova linha de transcrição
`onAgentSpeaking`	`(speaking: boolean) => void`	Agente começa / para de falar
`onUserSpeaking`	`(speaking: boolean) => void`	Usuário começa / para de falar (VAD local)
`onError`	`(message: string) => void`	Erro fatal
`onBusy`	`(retryAfterSeconds: number) => void`	Limite de sessões simultâneas atingido

<VoiceAgentWidget
  sdkKey="sua-chave"
  backendUrl="https://sdk.skia.com.br"
  showTranscript={false}
  startMuted={true}
  onStatus={(status) => console.log('status:', status)}
  onError={(msg) => alert('Erro: ' + msg)}
  onBusy={(retryAfter) => console.log(`Tente novamente em ${retryAfter}s`)}
/>

Opção 3 — Hook React (`useVoiceAgent`)

Para projetos React que precisam de UI totalmente personalizada. O hook gerencia toda a lógica de conexão, áudio e estado — você constrói a interface.

import { useVoiceAgent } from 'voice-agent-react'

export default function MeuAgente() {
  const {
    startConversation,
    stopConversation,
    mute,
    unmute,
    isMuted,
    status,
    isAgentSpeaking,
    isUserSpeaking,
    transcript,
    busyRetryAfter,
  } = useVoiceAgent({
    sdkKey: 'sua-chave-aqui',
    backendUrl: 'https://sdk.skia.com.br',
    onError: (msg) => console.error(msg),
  })

  return (
    <div>
      <p>Status: {status}</p>
      {busyRetryAfter && <p>Ocupado. Tente em {busyRetryAfter}s</p>}

      <button onClick={startConversation} disabled={status !== 'idle'}>
        Iniciar
      </button>
      <button onClick={stopConversation} disabled={status === 'idle'}>
        Encerrar
      </button>
      <button onClick={isMuted ? unmute : mute}>
        {isMuted ? 'Ativar mic' : 'Mutar'}
      </button>

      <ul>
        {transcript.map((entry, i) => (
          <li key={i}><strong>{entry.role}:</strong> {entry.text}</li>
        ))}
      </ul>
    </div>
  )
}

Retorno do hook

Valor	Tipo	Descrição
`startConversation`	`() => Promise<void>`	Inicia a sessão de voz
`stopConversation`	`() => void`	Encerra a sessão
`mute`	`() => void`	Muta o microfone
`unmute`	`() => void`	Desmuta o microfone
`isMuted`	`boolean`	Microfone está mutado
`status`	`AgentStatus`	Estado atual da sessão
`isAgentSpeaking`	`boolean`	Agente está falando agora
`isUserSpeaking`	`boolean`	Usuário está falando agora (VAD)
`transcript`	`TranscriptEntry[]`	Histórico da conversa
`busyRetryAfter`	`number \| null`	Segundos para retry quando `status === 'busy'`

Tipo `AgentStatus`

type AgentStatus = 'idle' | 'connecting' | 'connected' | 'busy' | 'error'

Compatibilidade com CSP

O SDK é compatível com políticas CSP restritivas (style-src sem 'unsafe-inline'). Toda estilização é via classes CSS no Shadow DOM — nenhum element.style é usado.

Adicione ao seu cabeçalho CSP:

Content-Security-Policy:
  script-src 'self' https://sdk.skia.com.br;
  connect-src 'self' wss://sdk.skia.com.br;

Visão geral​

Arquivos disponíveis​

Arquivos versionados (estáveis, com SRI)​

Aliases sem versão (sempre o mais recente)​

Hashes SRI​

Endpoints​

Formato de /sdk/sri-hashes.json​

Opção 1 — Web Component (HTML puro)​

Inclusão com SRI (produção)​

Atributos disponíveis​

Opção 2 — Componente React (<VoiceAgentWidget>)​

Inclusão via UMD (CDN)​

Uso básico​

Props de UI​

Props do agente​

Callbacks​

Opção 3 — Hook React (useVoiceAgent)​

Retorno do hook​

Tipo AgentStatus​

Compatibilidade com CSP​