SDK Callix — conceitos e capacidades

O que é o SDK

Definição

O SDK da Callix coloca o telefone dentro da aplicação do cliente. O agente atende, disca, coloca em espera e qualifica a chamada sem sair da tela onde já trabalha — e o áudio trafega pelo próprio browser, sem instalação de softphone, plugin ou VPN na máquina dele.

Tecnicamente, é um softphone WebRTC distribuído como biblioteca, com uma máquina de estados de operador em volta. A aplicação parceira constrói a interface que quiser; a Callix entrega a telefonia, o estado do agente e o contexto da chamada.

Capacidades

O que a integração passa a ter

O problema que resolve

Contexto operacional

Sem SDK, o agente opera em duas telas: o sistema onde estão o cliente e o histórico, e a tela de operação da Callix, onde está o telefone. Ele copia número de um lado para o outro, alterna janelas durante a ligação e registra o desfecho duas vezes — uma na qualificação da Callix, outra no sistema próprio. Erro de digitação e registro esquecido nascem nessa fronteira.

Arquitetura de pacotes

Três bibliotecas publicadas no npm sob @callixbrasil

Um pacote é uma biblioteca que o desenvolvedor instala com um comando e passa a usar no próprio código. São três, e a divisão não é arbitrária: cada um roda num lugar diferente, e é isso que mantém a chave de API fora do browser.

Arquitetura de integração

A fronteira de confiança e o caminho do áudio

Quatro atores e uma linha que a chave de API nunca cruza. O áudio não passa pelo servidor do parceiro — vai direto do browser do agente para a plataforma.

Obrigações que isso impõe à aplicação parceira

• Ter um backend. Não há integração segura apenas com HTML e JavaScript no browser — algum servidor precisa guardar a chave de API.
• Servir a aplicação por HTTPS. O browser não libera o microfone fora de contexto seguro (localhost é a exceção, para desenvolvimento).
• Mapear usuário da aplicação → usuário da Callix. O token é emitido para um login específico da plataforma.

Modelo de estados

O conceito central da integração

Aqui está a inversão em relação a uma API REST convencional. A aplicação não pergunta se a chamada foi atendida. Ela declara: quando o estado for X, mostre isto. O SDK empurra o estado; a tela é uma consequência.

Os comandos — ficar disponível, entrar em pausa, discar, desligar — são intenções sem retorno. Não devolvem sucesso nem erro. Quem confirma é a próxima transição de estado. Um comando inválido no estado atual é descartado silenciosamente.

A integração em três blocos

O restante é interface, construída pelo parceiro

A superfície de contato com o SDK é pequena. Estes três blocos cobrem autenticação, inicialização e consumo de estado; tudo além disso é a interface que a aplicação parceira já sabe construir.

1. No servidor: trocar a chave por um token

// roda no backend do parceiro — a chave nunca sai daqui
const callix = new CallixServerSdk(dominio, process.env.CALLIX_API_KEY);

const sessao = await callix.createUserSessionForClientSdk(loginDoAgente);

// devolve para a tela apenas isto:
return { userSessionToken: sessao.userSessionToken };

A autenticação do usuário da aplicação acontece antes desta linha, e é ela que determina qual login Callix pode ser operado.

2. Na tela: ligar o SDK

<CallixClientProvider domain={dominio} userSessionToken={token}>
  <TelaDeAtendimento />
</CallixClientProvider>

A partir daqui, qualquer componente dentro dessa árvore enxerga o operador.

3. Em qualquer componente: ler estado e comandar

const estado = useCallOperatorState();        // { state: 'callInProgress', call }
const { makeManualCall } = useCallOperatorControls();
const info = useCallOperatorCurrentCallInfo(); // campanha, lista, contato

// telefone e rótulo do contato vêm daqui, não de call.data — chega logo após callRinging
if (info?.type === 'campaign') return <FichaDoCliente contato={info.info.campaignContact} />;

São 17 hooks no total, cobrindo estado, controles da chamada, áudio, pausas e qualificações. Nenhum deles exige conhecimento de WebRTC.

Glossário

Termos que aparecem neste documento

Escopo e limites

O que está e o que não está coberto

O SDK cobre voz. Os três pacotes não expõem chat, WhatsApp, e-mail ou qualquer canal além de telefonia — toda a superfície pública é telefônica. Integrações de outros canais seguem por caminhos distintos da plataforma.

Dentro de voz, a operação do agente tem duas origens de chamada: a campanha entrega a chamada ao agente, e o agente disca manualmente. É o que CallInfo reflete — os dois únicos formatos de contexto que o SDK entrega são campaign e manual.

Atendimento receptivo de fila não é atendido pelo SDK. Uma operação que precise receber chamadas de fila continua na tela de operação da Callix para essa parte — o SDK não substitui esse fluxo. Vale confirmar a origem das chamadas antes de dimensionar a integração: se a operação for majoritariamente receptiva, o SDK cobre menos do que parece à primeira vista.

Outros limites

• Não é SDK de supervisão nem de relatório. Há exatamente um evento público (userSessionDropped). O monitoramento da operação continua pela API e pelos relatórios da plataforma.
• Execução em browser. Depende de WebRTC e de microfone; não atende cenários de automação sem interface.
• Mobile via WebView. O exemplo React Native de referência não integra o SDK nativamente — ele carrega a aplicação web dentro de uma WebView. É um caminho funcional, distinto de um app nativo.

Comportamentos que exigem decisão

Pontos a definir no desenho da integração

Pré-requisitos e questões de escopo

O que precisa estar definido antes de estimar

Sobre o conteúdo

Base do documento

O conteúdo deste documento é baseado nos pacotes publicados e na aplicação de demonstração construída sobre o SDK 1.0.1, executada contra um tenant de homologação. A aplicação apresenta o softphone e, ao lado, um registro de cada transição de estado e cada comando com marcação de milissegundos.