Eventos em Tempo Real (SSE/WebSocket)

16. Eventos em Tempo Real (SSE/WebSocket)#

Receba eventos em tempo real sem polling. Ideal para dashboards e chatbots.

GET/v1/instances/{instanceId}/events (SSE)#

Server-Sent Events stream.

Auth: Header Authorization: Bearer <jwt> ou X-API-Key: <key>

Falha de auth no stream: o handler de SSE/WS colapsa qualquer falha de validação de token/empresa em 401 invalid or missing token antes de abrir o stream. A regra de empresa ativa continua valendo no middleware de auth normal, mas estes handlers de streaming retornam 401 para credencial ausente, inválida, empresa inexistente/suspensa ou falha na consulta de empresa.

Query Parameters:

Parametro Tipo Descricao
events string Filtro de eventos (separados por virgula). Ex: message.received,connection.update
last_event_id string Cursor opcional para replay curto. Se informado, o servidor reenviara eventos buffered posteriores a esse ID

Resume/Replays — cursor durável (recomendado): todo evento persistido no outbox sai com id: <cursor> na linha SSE (e campo cursor no JSON) — o ID monotônico da linha event_logs do tenant. Guarde o maior cursor processado e reconecte enviando-o em Last-Event-ID (ou ?last_event_id=): o servidor faz catch-up direto do banco (id > cursor, em ordem, até 2000 eventos por conexão) antes de virar live — nenhum evento é perdido, independente de quanto tempo o cliente ficou fora. Vários consumidores podem manter cursors independentes; cada um retoma do próprio ponto. Se o cursor for mais antigo que a janela de retenção do outbox (linhas já podadas) ou o backlog exceder o lote de catch-up, o servidor emite o evento de controle catchup_gap — ao recebê-lo, ressincronize o estado local via REST (/chats, /messages, /events/history) e siga o stream. Eventos duplicados nunca são entregues na mesma conexão (dedupe por cursor no servidor); entre conexões, descarte qualquer evento com cursor ≤ o último processado.

Resume legado (UUID): um Last-Event-ID não numérico (o event_id UUID) continua aceito e usa o buffer em memória com os 100 eventos mais recentes por instância — só cobre quedas curtas e não sobrevive a restart da API. Prefira o cursor.

Limite por instância: máximo de 20 conexões SSE/WebSocket simultaneas por instância. Excesso retorna 429 Too Many Requests.

Formato dos eventos:

text
event: connected
data: {"instance_id": "84c2e480-..."}

event: message.received
id: evt_1234
data: {"event_id":"550e8400-...","type":"message.received","instance_id":"84c2e480-...","timestamp":"2026-03-07T15:30:45.123Z","data":{...}}

: heartbeat

Evento live-only do Audit Timeline: quando o worker grava uma linha em stealth_audit_events, ele pública um evento SSE/WS stealth.audit_event no mesmo canal Redis por instância. Esse evento existe para refresh imediato da UI e não entra em webhooks nem em GET /events/history.

Payload stealth.audit_event:

json
{
  "id": 42,
  "instance_id": "84c2e480-...",
  "event_type": "connection.opened",
  "event_data": {
    "proxy_city": "sao-paulo",
    "spec": "hello_chrome_120"
  },
  "occurred_at": "2026-04-20T22:30:00Z",
  "created_at": "2026-04-20T22:30:00Z"
}

Vocabulario controlado de event_type (v1):

  • fingerprint.assigned
  • fingerprint.rotated
  • warmup.phase_changed
  • warmup.bypass_granted
  • warmup.bypass_expired
  • connection.opened
  • connection.closed
  • connection.banned
  • hygiene.applied
  • humanize.applied
  • stealth.inbound_first.blocked
  • stealth.app_version_canary_started
  • stealth.app_version_fleet_applied
  • stealth_transport.debug_enabled
  • stealth_transport.debug_renewed
  • stealth_transport.debug_expired

Notas warmup:

  • warmup.phase_changed e gravado de forma transacional junto com o UPDATE tenant_instances.warmup_phase.
  • warmup.bypass_granted e emitido pela ação superadmin de bypass de warmup e carrega reason, ticket_id, token e expires_at dentro de event_data.
  • hygiene.applied e emitido uma vez por alteração bem-sucedida (push_name, photo, status) e carrega type + value dentro de event_data.

Exemplo com curl:

bash
curl -N \
  -H "Authorization: Bearer eyJ..." \
  "https://api.catcher.one/v1/instances/84c2e480/events?events=message.received,connection.update"

Exemplo com JavaScript (fetch streaming):

javascript
const response = await fetch(
  'https://api.catcher.one/v1/instances/84c2e480/events?events=message.received',
  {
    headers: { Authorization: `Bearer ${token}` }
  }
);
// Leia response.body como ReadableStream e parseie o protocolo SSE.

GET/v1/instances/{instanceId}/events/history#

Histórico de eventos persistidos com paginação baseada em cursor (retenção de 7 dias). É o caminho para reconciliar o que o seu servidor perdeu: guarde o último event_id processado e leia after=<event_id> em lotes de até 200 até has_more=false — em vez de um GET .../message/{id} por mensagem pendente. Veja Boas Práticas de Integração.

Auth: Bearer JWT ou API Key

Query Parameters:

Parametro Tipo Descricao
limit int Máximo de eventos (1-200, padrão 50)
before string Cursor: event_id para buscar eventos anteriores (DESC)
after string Cursor: event_id para buscar eventos posteriores (ASC, catch-up)
since string Timestamp RFC3339 para buscar eventos a partir de (ASC)
types string Filtro por tipo(s) de evento, separados por virgula. Ex: message.received,message.sent. Um nome genérico message.<ação> cobre as formas específicas <kind>.<ação> emitidas com EVENT_NAMING=specific (text.received, image.received, …) — mesma semântica do filtro events= de SSE/WS e do matching de webhooks. Um nome específico continua exato.
contains string Busca por substring em qualquer campo principal do evento: event_id, type, instance_id, timestamp e no JSON data (chaves e valores). Ex: contains=ABC123 encontra todos eventos que referenciam o WhatsApp message ID ABC123; contains=message.sent filtra por tipo; contains=2026-04-23 encontra eventos daquela data

Resposta 200:

json
{
  "events": [
    {
      "event_id": "ca5e3b45-055a-4ccc-be37-cb9d76d25887",
      "type": "message.received",
      "instance_id": "be23db3e-900d-4194-98ca-7a1deb2157a5",
      "timestamp": "2026-04-04T17:34:55.965Z",
      "data": {
        "message_ids": ["ABC123"],
        "chat": "5511999999999@s.whatsapp.net",
        "from": "5511999999999@s.whatsapp.net",
        "type": "text",
        "content": "Ola!"
      }
    }
  ],
  "has_more": true
}

Correlação de eventos com mensagens: Use contains com o UUID Catcher da mensagem (message_id / elemento de message_ids) para encontrar todos os eventos relacionados (received, sent, delivered, read, deleted, edited). O UUID Catcher é o id primário dos eventos; a chave nativa do WhatsApp vem à parte nos campos wa_* (desde 2026-10-21).

Busca paginada: quando contains estiver presente, a paginação (before / after) continua sendo aplicada sobre o conjunto filtrado. Exemplo: limit=50&contains=oi retorna os 50 eventos mais recentes que contenham oi; o próximo before=<ultimo_event_id> retorna os 50 matches seguintes, não apenas os próximos 50 eventos brutos.


GET/v1/instances/{instanceId}/events/stats#

Estatísticas agregadas dos eventos de uma instância.

Auth: Bearer JWT ou API Key

Resposta 200:

json
{
  "total_count": 1523,
  "count_by_type": {
    "message.received": 450,
    "message.sent": 320,
    "message.delivered": 310,
    "message.read": 280
  },
  "latest_timestamp": "2026-04-04T17:34:55.965Z"
}

GET/v1/instances/{instanceId}/ws (WebSocket)#

Conexão WebSocket para eventos em tempo real.

Auth: Header Authorization ou X-API-Key (mesma regra do SSE).

Query Parameters: events e last_event_id. A autenticação não aceita mais token em query string.

Comportamento:

  • Upgrade para WebSocket (101 Switching Protocols)
  • Somente leitura (servidor envia, cliente recebe)
  • Ping a cada 30s para manter a conexão
  • Mensagens em formato JSON
  • Replay inicial opcional a partir de last_event_id
  • Se o limite de 20 subscribers por instância for excedido, a API responde 429 antes do upgrade

Exemplo com Node.js (ws com headers):

javascript
const WebSocket = require('ws');

const ws = new WebSocket(
  'wss://api.catcher.one/v1/instances/84c2e480/ws?events=message.received',
  {
    headers: { Authorization: `Bearer ${token}` }
  }
);

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Evento:', data.type, data);
};

GET/v1/instances/{instanceId}/calls (histórico de chamadas)#

Lista o histórico persistido de chamadas de uma instância (mais recente primeiro, paginado), a partir da tabela tenant call_logs. A lista "Encerradas" da página de chamadas ao vivo do Console é montada a partir dos eventos SSE (call.recorded / call.ended) recebidos durante a sessão — num refresh ela fica vazia. Este endpoint é a fonte durável para reconstruir esse histórico ao carregar a tela (combinado com o feed ao vivo).

Cada item traz o media_id da gravação + a duration_seconds real de conversa quando a chamada foi atendida e gravada (ambos null caso contrário). Nunca há URL de CDN da Meta na resposta — a gravação é baixada pelo endpoint de mídia da BiaZap usando media_id.

Auth: Authorization: Bearer <token> ou X-API-Key.

Escopo: superadmin lê qualquer instância; um chamador comum só lê uma instância da própria empresa (404 INSTANCE_NOT_FOUND caso contrário).

Query params:

  • limit — itens por página (default 50, máximo 200)
  • page — página 1-based (default 1)

Resposta 200:

json
{
  "calls": [
    {
      "call_id": "AC354C9DCD3C31E4F280710749CBF5DA",
      "phone": "554192464230",
      "from": "554192464230@s.whatsapp.net",
      "direction": "inbound",
      "status": "ended",
      "duration_seconds": 42,
      "media_id": "0f4c1e2a-...",
      "is_group": false,
      "end_reason": "hangup",
      "timestamp": "2026-07-02T13:00:57Z",
      "accepted_at": "2026-07-02T13:00:59Z",
      "ended_at": "2026-07-02T13:01:41Z",
      "created_at": "2026-07-02T13:00:57Z"
    }
  ],
  "page": 1,
  "limit": 50,
  "has_more": false
}
  • call_id — id da chamada do WhatsApp (o mesmo do evento call.received)
  • phone / from — identidade do chamador (phone vazio para LID/grupo); nunca URL de CDN da Meta
  • direction — sempre inbound (o call_logs registra apenas OFFERs de entrada)
  • status — offered | accepted | rejected | ended
  • duration_seconds / media_id — duração real e gravação (via VoIP); null quando a chamada não foi gravada
  • timestamp / accepted_at / ended_at / created_at — RFC3339 (UTC); null quando ausente
  • Ordenado por created_at decrescente (mais recente primeiro). has_more=true indica que há a próxima página.

Nota (linkage da gravação): o media_id + duration_seconds são gravados na linha call_logs pelo worker no caminho call.recorded (VoIP). Instâncias sem VoIP habilitado ou chamadas não atendidas ficam com esses campos null.

Áudio de chamada no canal OFICIAL (meta_cloud)#

Chamadas do canal oficial (WhatsApp Business Calling API) chegam pelo webhook calls. A sinalização (call.received / call.ended + a linha call_logs) funciona por si só; o áudio depende da ponte de mídia WebRTC, desligada por padrão.

Com OFFICIAL_CALLING_MEDIA_ENABLED=true e a instância listada em OFFICIAL_CALLING_ANSWER_INSTANCES, a API atende a chamada de entrada automaticamente: gera o SDP answer, executa a sequência obrigatória da Meta (pre_accept → transporte conectado → accept), e a partir daí o áudio flui. O que muda para o consumidor da API:

  • a gravação vira Ogg/Opus (mime_type: "audio/ogg", Source: "official-call-recording") em vez do WAV do canal não-oficial — ~10× menor para a mesma chamada, porque o áudio já chega codificado em Opus e é gravado sem decodificar. Continua sendo um media_id da BiaZap; nunca uma URL de CDN da Meta.
  • call.recorded é emitido normalmente ao encerrar, com media_id + duration_seconds.
  • transcrição ao vivo, agente de voz com IA e o softphone do Console funcionam sem mudança: a ponte publica nos mesmos canais canônicos de PCM.

Limite conhecido — chamada "listen-only". O áudio de saída (nossa voz para o chamador) depende de a oferta da Meta incluir um codec que sabemos codificar. O encoder embarcado é G.711 µ-law (Go puro, sem dependência de sistema). Se a oferta vier só com Opus, a chamada é atendida mesmo assim, mas em modo apenas escuta: gravação, transcrição e o agente de IA continuam recebendo o áudio; só o retorno de voz fica indisponível até que um encoder Opus seja habilitado. Nesse caso o log registra answering listen-only.

O SDP (offer e answer) nunca aparece em evento, payload de webhook, SSE ou resposta de endpoint — é estritamente interno ao servidor.

GET/v1/instances/{instanceId}/calls/active (chamadas VoIP ao vivo)#

Lista as chamadas VoIP ao vivo (atendidas) de uma instância. Serve para restaurar a página de chamadas ao vivo do Console após um refresh do navegador (ou uma reconexão do SSE): uma chamada em andamento reaparece na tela em vez de sumir até a próxima chamada. Sem esse endpoint a página só conhece uma chamada pelo evento transitório call.received.

Fonte da verdade: o worker VoIP mantém um hash Redis por instância (uma entrada por chamada, gravada ao atender e removida ao encerrar, com TTL de segurança). Este endpoint apenas lê esse estado — não há RPC para o worker.

Auth: Authorization: Bearer <token> ou X-API-Key.

Escopo: superadmin lê qualquer instância; um chamador comum só lê uma instância da própria empresa (404 INSTANCE_NOT_FOUND caso contrário).

Resposta 200:

json
{
  "calls": [
    {
      "call_id": "AC354C9DCD3C31E4F280710749CBF5DA",
      "phone": "554192464230",
      "from": "554192464230@s.whatsapp.net",
      "started_at": 1774725057
    }
  ]
}
  • call_id — id da chamada do WhatsApp (o mesmo do evento call.received)
  • phone / from — identidade do chamador (BR-normalizada, LID→telefone resolvido); nunca uma URL de CDN da Meta
  • started_at — unix (segundos) de quando a chamada ficou ativa (mídia fluindo)
  • Ordenado por started_at decrescente (mais recente primeiro). Sem VoIP habilitado / sem chamadas ao vivo → { "calls": [] }.

GET/v1/calls/{callID}/audio (WebSocket — áudio da chamada ao vivo, bidirecional)#

Faz upgrade para WebSocket e transporta o áudio da chamada nos dois sentidos:

  • Downlink (Fase 1 — "ouvir ao vivo"): o servidor envia o áudio decodificado do interlocutor (callID) como mensagens binárias de PCM — o navegador remonta o áudio concatenando os frames e toca via Web Audio API.
  • Uplink (Fase 2 — "falar ao vivo"): o mesmo WebSocket também recebe mensagens binárias de PCM do navegador (áudio do microfone do operador). O servidor publica cada frame no canal Redis biazap:voip:audio:up:<callID>; o worker alimenta esses frames no loop de envio da chamada, então o interlocutor ouve o operador. Frames não-binários ou fora do tamanho de 640 bytes são descartados.

Pré-requisito: a instância precisa estar com VoIP habilitado (VOIP_ENABLED=true) e ter atendido a chamada (auto-answer). Só chamadas atendidas pela instância (que é participante da mídia) têm áudio ao vivo. Hoje apenas o provider whatsmeow atende chamadas (STAGING).

Auth: Header Authorization: Bearer <token> ou X-API-Key (idêntica ao /ws — sem token em query string).

Escopo: o callID deve pertencer a uma chamada de uma instância da sua empresa (verificado contra call_logs). Superadmin pode ouvir qualquer chamada.

Formato de cada frame binário (contrato fixo — whats-shared/pkg/voipaudio, idêntico nos dois sentidos):

  • PCM cru, 16 kHz, mono (1 canal)
  • signed 16-bit little-endian
  • 20 ms por frame = 320 amostras = 640 bytes (uma mensagem WebSocket binária = um frame). No uplink, o navegador deve enviar frames de exatamente 640 bytes; qualquer outra coisa (frame de tamanho diferente ou mensagem de texto) é descartada.

Comportamento:

  • Upgrade para WebSocket (101 Switching Protocols)
  • Bidirecional: o servidor envia frames binários (downlink) e recebe frames binários do cliente (uplink)
  • Ping a cada 30s para manter a conexão
  • Encerra quando o cliente desconecta ou a chamada termina (o stream fica em silêncio)
  • Máximo de 8 ouvintes simultâneos por chamada — excesso retorna 429 antes do upgrade. O uplink não tem política de escritor único na v1 (last-writer/intercalado); na prática há um operador por chamada
  • 404 quando o callID não pertence à sua empresa; 503 quando o áudio ao vivo está indisponível

Descoberta da chamada ativa: reutilize o event stream. O evento call.received (webhook/SSE/WS) já carrega o call_id (no data), o phone e o instance_id (no envelope do evento) — o call_id é o mesmo callID deste endpoint, estável durante toda a chamada. Abra o WebSocket assim que receber call.received da instância que atende.

Transporte (contrato interno): o worker publica cada frame decodificado no canal Redis Pub/Sub biazap:voip:audio:down:<callID> (downlink); esta rota assina o canal e encaminha ao WebSocket. No sentido inverso (uplink), esta rota publica cada frame binário recebido do navegador em biazap:voip:audio:up:<callID>; o worker faz PSUBSCRIBE de biazap:voip:audio:up:* e alimenta cada frame no loop de envio da chamada viva (via o seam Call.PushAudioFrame do meowcaller). Os dois sentidos são ligados/ desligados juntos por VOIP_LIVE_AUDIO_ENABLED (default ligado quando VoIP está ligado).

Transcrição ao vivo (mensagens de TEXTO no mesmo WebSocket). Além dos frames binários de áudio, este WebSocket também emite mensagens de TEXTO (JSON) com a transcrição ao vivo das duas pontas da chamada. Enquanto houver ao menos um ouvinte conectado, a API (nunca o worker — habilitar transcrição não derruba sessões WhatsApp) acumula o PCM de cada sentido separadamente, corta em trechos por VAD de energia (~5 s ou uma pausa de silêncio, o que vier primeiro; trechos quase-silenciosos são descartados), transcreve cada trecho via OpenAI e envia o resultado como um frame de TEXTO. Binário = áudio; texto = transcrição.

Cada mensagem de texto tem a forma:

json
{ "type": "transcript", "speaker": "caller", "text": "olá, tudo bem?", "start_ms": 1000, "end_ms": 4200, "is_final": true }
  • type — sempre "transcript" (distingue do áudio binário).
  • speaker — "caller" (a parte remota / downlink) ou "operator" (o lado local / uplink / microfone).
  • text — o texto transcrito (pt-BR).
  • start_ms / end_ms — milissegundos na linha do tempo compartilhada da chamada: os dois lados são carimbados contra uma única origem t0 (o instante em que a API começou a transcrever a chamada) com o mesmo relógio, então start_ms é comparável globalmente entre os speakers — ordenar por start_ms produz a ordem cronológica correta mesmo intercalando caller e operator.
  • is_final — true na v1 (segmentos completos; o campo deixa espaço para parciais is_final:false numa fase futura).

Modelo: gpt-4o-transcribe (com fallback whisper-1 quando o primeiro retorna HTTP 4xx), language=pt. Gate por env VOIP_TRANSCRIBE_ENABLED (default ligado quando OPENAI_API_KEY está setado; sem a chave é um no-op gracioso). Só chamadas com ouvinte ativo são transcritas (controle de custo — ref-count: começa no primeiro ouvinte, para no último). A transcrição carrega apenas texto + speaker + timestamps — nunca URL de CDN da Meta nem handle de mídia. OpenAI é uma API first-party comum (egress normal, cliente HTTP padrão), não um host Meta/WhatsApp, então não trafega pelo proxy por-instância.

Ganho automático (normalização). O lado do cliente de uma chamada é o downlink decodificado (MLow, PCM 16 kHz), inerentemente mais baixo que o mic do operador (uplink). Sem ganho, o VAD de energia super-filtra o lado do cliente (o transcript do CLIENTE some, só sobra o VOCÊ) e mesmo um trecho que passa chega baixo demais para a OpenAI transcrever bem. Por isso todo trecho é peak-normalizado para um nível-alvo fixo (~-3 dBFS) com teto de ganho (~24 dB) e um piso de silêncio (~-46 dBFS): o cliente baixo é empurrado para cima e o operador alto fica no mesmo nível — as duas pontas ficam audíveis para a OpenAI. O silêncio/ruído-de-conforto genuíno (abaixo do piso) não é amplificado, então não vira falso "voiced". A decisão do VAD roda sobre o áudio já normalizado, então o limiar é relativo ao nível impulsionado (não à amplitude crua) — é o que faz o cliente baixo cruzar a porta em vez de ser descartado. Aplicado às DUAS pontas (idempotente para o operador, que já é alto).

VAD (corte de trechos). O áudio de cada lado é cortado em trechos por um VAD de energia, com o objetivo de gerar trechos grandes e coerentes (~3–12 s): um trecho maior dá à OpenAI a frase inteira como contexto, o que aumenta muito a acurácia (trechos curtos e picotados — "É...", "Uma garota.", "Bom dia." — deixam o modelo sem contexto e vêm fragmentados/errados). O corte preferencial é a pausa natural, mas só depois de um piso de ~3 s (VOIP_TRANSCRIBE_MIN_CHUNK_MS): uma pausa/respiração curta nos primeiros segundos não fecha o trecho, então uma frase com pausas no meio permanece um único trecho coerente. Passado o piso, o trecho fecha após ~800 ms de silêncio depois da fala (VOIP_TRANSCRIBE_SILENCE_GAP_MS) — sem esperar a janela cheia. Só quando a fala é contínua o trecho é forçado na janela máxima de 12 s (VOIP_TRANSCRIBE_MAX_WINDOW_MS, sempre o teto, independente do piso). Num corte forçado, uma cauda de ~250 ms (VOIP_TRANSCRIBE_OVERLAP_MS, 0 desativa) é reaproveitada no próximo trecho, de modo que uma palavra na fronteira seja capturada em pelo menos um dos dois (uma repetição eventual é melhor que uma palavra perdida). Um trecho precisa de pelo menos ~350 ms de fala acima do limiar (VOIP_TRANSCRIBE_MIN_VOICED_MS) para ser transcrito — baixo o bastante para não descartar falas curtas ("beleza?"), alto o bastante para descartar trechos quase-silenciosos na origem (um trecho que cresceu com o piso mas é quase todo silêncio ainda é descartado).

Anti-alucinação + continuidade. Whisper / gpt-4o-transcribe alucinam texto em inglês ou línguas aleatórias sobre silêncio/ruído mesmo com language=pt. O piso de fala do VAD acima é a primeira camada (trechos quase-silenciosos nem chegam à OpenAI), mas não é a única — por isso ele pode ficar baixo sem re-alucinar: (2) cada request carrega um prompt que ancora o modelo no contexto pt-BR de atendimento + temperature=0 (decodificação determinística), tanto no modelo primário quanto no fallback; o prompt também carrega um contexto rolante por speaker — as últimas ~1–2 falas finais daquele lado (buffer curto, limitado a ~300 caracteres) são realimentadas no request seguinte, de modo que o modelo mantém continuidade (nomes, termos, fluxo da frase) entre os trechos — técnica clássica de coerência do Whisper; (3) um pós-filtro descarta as alucinações canônicas de silêncio (ex.: "Thank you.", "Obrigado por assistir", "Legendas pela comunidade Amara.org", ...) e segmentos curtos/só-pontuação demais para serem fala real. Todos os knobs do VAD são ajustáveis ao vivo (sem redeploy): VOIP_TRANSCRIBE_MIN_VOICED_MS (ms, default 350), VOIP_TRANSCRIBE_ENERGY_THRESHOLD (RMS normalizado [0,1) medido sobre o frame já normalizado, default 0.01), VOIP_TRANSCRIBE_MAX_WINDOW_MS (ms, default 12000), VOIP_TRANSCRIBE_MIN_CHUNK_MS (ms, default 3000; 0 desativa o piso), VOIP_TRANSCRIBE_SILENCE_GAP_MS (ms, default 800) e VOIP_TRANSCRIBE_OVERLAP_MS (ms, default 250; 0 desativa a sobreposição); valor ausente/inválido mantém o default.

Persistência (chamada encerrada). Cada segmento is_final é gravado na tabela tenant call_transcripts no mesmo momento em que é publicado ao vivo, para que a transcrição de uma chamada já encerrada possa ser recuperada depois (o stream ao vivo some quando a chamada termina). A recuperação é o endpoint GET /v1/instances/{instanceId}/calls/{callID}/transcript abaixo. A gravação grava só quando a empresa dona da chamada é resolvida (um ouvinte superadmin não resolve a empresa e portanto não persiste — o stream ao vivo continua igual). A gravação em si é fonte de dado separada (evento call.recorded → media_id), inalterada.

Exemplo no navegador (áudio via Web Audio + transcrição via texto):

javascript
// callId veio do evento call.received (data.call_id); instanceId do envelope.
const ws = new WebSocket(`wss://api.catcher.one/v1/calls/${callId}/audio`, [
  // como no /ws, o token vai por header/subprotocol conforme o cliente
]);
ws.binaryType = 'arraybuffer';

const ctx = new AudioContext({ sampleRate: 16000 });
let playAt = ctx.currentTime;
ws.onmessage = (event) => {
  // Frame de TEXTO → transcrição ao vivo; frame binário → áudio PCM.
  if (typeof event.data === 'string') {
    const seg = JSON.parse(event.data);
    if (seg.type === 'transcript') {
      console.log(`[${seg.speaker}] ${seg.text}`); // renderize na legenda ao vivo
    }
    return;
  }
  const pcm = new Int16Array(event.data);          // s16le, mono, 16 kHz
  const buf = ctx.createBuffer(1, pcm.length, 16000);
  const ch = buf.getChannelData(0);
  for (let i = 0; i < pcm.length; i++) ch[i] = pcm[i] / 32768;
  const src = ctx.createBufferSource();
  src.buffer = buf;
  src.connect(ctx.destination);
  playAt = Math.max(playAt, ctx.currentTime);
  src.start(playAt);
  playAt += buf.duration;                          // enfileira em sequência
};

Nota de disciplina (STAGING): a mídia da chamada trafega por UDP/SRTP direto para a malha de relay da Meta, fora do túnel HTTP-CONNECT por instância — igual à gravação de chamada (ver call.recorded). Não habilite VoIP em instância de cliente de produção. Este endpoint apenas encaminha o PCM já decodificado (nenhuma URL de CDN da Meta é exposta).

GET/v1/instances/{instanceId}/calls/{callID}/transcript (transcrição persistida)#

Retorna a transcrição persistida de uma chamada VoIP — a cópia durável do que o WebSocket de áudio (/v1/calls/{callID}/audio) transmitiu ao vivo. Serve para ler a transcrição de uma chamada já encerrada (o stream ao vivo some quando a chamada termina).

Auth/escopo (igual a .../calls/active): um superadmin lê qualquer instância; um chamador comum lê só instâncias da própria empresa.

Resposta 200:

json
{
  "segments": [
    { "speaker": "operator", "text": "bom dia, como posso ajudar?", "start_ms": 500,  "end_ms": 1800 },
    { "speaker": "caller",   "text": "quero saber o preço",          "start_ms": 1000, "end_ms": 1900 },
    { "speaker": "caller",   "text": "obrigado!",                     "start_ms": 2000, "end_ms": 2600 }
  ]
}
  • segments — lista ordenada por start_ms crescente; [] (nunca null) quando a chamada não tem transcrição persistida.
  • speaker — "caller" (parte remota) ou "operator" (lado local).
  • text — o texto transcrito (pt-BR).
  • start_ms / end_ms — milissegundos dentro da sessão de transcrição daquele speaker (não relógio de parede). Sem URL de CDN da Meta nem handle de mídia.

Escopo por (instance_id, call_id). 404 INSTANCE_NOT_FOUND se a instância não pertence à empresa do chamador (não-superadmin).

POST/v1/instances/{instanceId}/calls/{callID}/answer (atender chamada — manual)#

Atende uma chamada 1:1 tocando (RINGING) numa instância em modo manual (VOIP_MANUAL_ANSWER_INSTANCES). A instância aceita a chamada, começa a gravar e faz o bridge do áudio ao vivo para o navegador do operador (abra o WebSocket /v1/calls/{callID}/audio para o mesmo call_id). Emite call.accepted.

Instâncias em modo manual não atendem sozinhas — quando chega um OFFER, o call.received vem com state:"ringing" (o sinal de que o softphone pode atender/rejeitar). Se ninguém atender dentro de VOIP_RING_TIMEOUT (default 45s), a chamada é auto-rejeitada. Instâncias em VOIP_AUTO_ANSWER_INSTANCES continuam atendendo automaticamente (comportamento inalterado).

Auth/escopo (igual a .../calls/active): superadmin qualquer instância; comum só as da própria empresa.

Resposta 200:

json
{ "status": "answered", "instance_id": "84c2e480-...", "call_id": "AABBCC..." }

400 INVALID_REQUEST (call_id vazio), 404 INSTANCE_NOT_FOUND, 503 VOIP_DISABLED (ponte RPC do worker não conectada / VoIP off), 502 VOIP_ANSWER_FAILED (a chamada não está mais tocando — já atendida/encerrada — ou o worker falhou).

POST/v1/instances/{instanceId}/calls/{callID}/reject (rejeitar chamada — manual)#

Rejeita uma chamada RINGING numa instância em modo manual. Emite call.rejected. Mesmo auth/escopo. Resposta 200:

json
{ "status": "rejected", "instance_id": "84c2e480-...", "call_id": "AABBCC..." }

503 VOIP_DISABLED, 502 VOIP_REJECT_FAILED, 404 INSTANCE_NOT_FOUND.

POST/v1/instances/{instanceId}/calls/place (discar — chamada de saída)#

Coloca uma chamada de saída da instância para um número e devolve o call_id para o Console abrir o WebSocket de áudio + o softphone. A chamada grava + transmite ao vivo + transcreve exatamente como uma chamada de entrada atendida; o áudio é o microfone do navegador do operador (roteado pelo uplink) — nenhum áudio de teste é tocado. O target é BR-normalizado no servidor (número, JID de telefone, ou @lid).

Ao discar, a API persiste um call_logs com direction:"outbound" e emite call.received com direction:"outbound" + state:"ringing" (o Console mostra a chamada e abre o softphone). Quando a parte remota atende, vem call.accepted; ao encerrar, call.ended + call.recorded.

Cadência natural (lesson #53): uma chamada por vez, ação deliberada do operador — nunca em rajada.

Auth/escopo: igual aos demais endpoints de call.

Corpo: { "target": "5541999998888" }

Resposta 202:

json
{ "status": "placing", "instance_id": "84c2e480-...", "call_id": "AABBCC...", "target": "5541999998888" }

400 INVALID_REQUEST (target vazio), 404 INSTANCE_NOT_FOUND, 503 VOIP_DISABLED, 502 VOIP_PLACE_FAILED (destino inacessível / worker falhou).

STAGING ONLY (mesmo caveat de gravação/VoIP): a mídia da chamada é UDP direto para o relay da Meta, fora do túnel proxy por instância. Não habilite VoIP numa instância de cliente de produção. Gate por VOIP_ENABLED + as allowlists VOIP_AUTO_ANSWER_INSTANCES / VOIP_MANUAL_ANSWER_INSTANCES.

POST/v1/instances/{instanceId}/calls/{callID}/hangup (encerrar chamada)#

Encerra de fato uma chamada VoIP ativa (envia o terminate ao WhatsApp) ou rejeita uma que ainda esteja tocando. É o "Encerrar chamada" real que o softphone não tinha (antes só encerrava o monitoramento do operador). Idempotente: encerrar uma chamada que já terminou responde 200.

Resposta 200: { "status": "hung_up", "instance_id": "...", "call_id": "..." }. 400 INVALID_REQUEST, 404 INSTANCE_NOT_FOUND, 503 VOIP_DISABLED, 502 VOIP_HANGUP_FAILED.

POST/v1/instances/{instanceId}/calling (habilitar chamadas no número oficial)#

Liga/desliga o recebimento de chamadas de voz num número do canal oficial (meta_cloud), via Graph API. Instâncias não-oficiais sempre recebem chamadas e recusam esta rota.

Body: { "enabled": true }

Resposta 200: { "instance_id": "...", "calling_enabled": true, "official": true }. 400 NOT_OFFICIAL_CHANNEL (instância não é meta_cloud), 400 JSON inválido, 404 INSTANCE_NOT_FOUND, 502 META_CALLING_SET_FAILED (a Meta recusou).

Agente de voz IA em tempo real (OpenAI Realtime, provider-swappable)#

Um agente de voz speech-to-speech que conversa por voz numa chamada VoIP ao vivo em pt-BR. É API-owned e reusa os mesmos canais Redis de PCM do softphone + transcrição (whats-shared/pkg/voipaudio): o agente escuta o downlink (a voz da outra ponta) e fala no uplink — como se fosse um "navegador virtual" —, então a gravação + a transcrição ao vivo continuam funcionando. A WebSocket da OpenAI Realtime é uma API first-party comum (cliente HTTP/WS padrão), não um host Meta/WhatsApp, então não trafega pelo proxy por instância. Provider-swappable: openai hoje, grok depois (compatível com a spec OpenAI Realtime — só troca base URL + key + model via env). Gate: VOIP_AI_AGENT_ENABLED (default ON com OPENAI_API_KEY).

Env (VOIP_AI_*, todas API-only — não reinicia o worker):

Env Default Papel
VOIP_AI_AGENT_ENABLED true (com OPENAI_API_KEY) Liga o serviço. false força off.
VOIP_AI_PROVIDER openai openai | grok.
VOIP_AI_REALTIME_MODEL gpt-realtime Model id da WS Realtime GA.
VOIP_AI_VOICE marin Voz default (override por-attach).
VOIP_AI_MAX_SESSION 5m Teto de duração de uma sessão de agente.
VOIP_AI_REALTIME_BASE_URL / VOIP_AI_REALTIME_API_KEY (cai para OPENAI_*) Override do provider — aponta a base URL/key para o Grok sem tocar a config OpenAI.
VOIP_AI_BETA_HEADER "" OpenAI-Beta header (vazio = interface GA; legado só se preciso).
VOIP_AI_LEG_AUDIO_ENABLED false (worker) Liga os canais de áudio por-leg (necessário só para o ai-sim; off = custo zero em chamadas normais).

O áudio da OpenAI Realtime é pcm16 24 kHz; o pipeline de chamada é 16 kHz — o agente reamostra 16↔24 internamente. O session.update usa a forma GA aninhada (session.audio.input/output, format {type:"audio/pcm"}, turn_detection server VAD, transcrição de entrada); recebe response.output_audio.delta (o nome legado response.audio.delta também é aceito). Um teste ao vivo contra a OpenAI real existe atrás de RUN_REALTIME_TEST=1 (não roda em CI).

GET / PUT /v1/instances/{instanceId}/ai-agent-config (persona padrão da instância)#

Configuração padrão por instância do agente de voz. GET retorna, PUT faz upsert:

json
{ "instance_id": "84c2e480-...", "enabled": false, "system_prompt": "Você é a Bia, atendente da loja...", "voice": "marin", "provider": "openai" }

PUT aceita campos parciais (enabled, system_prompt, voice, provider); um provider inválido (≠ openai/grok) responde 400 INVALID_REQUEST. Escopo por empresa (superadmin em qualquer instância; caller normal só na própria).

POST /v1/instances/{instanceId}/calls/{callID}/ai-agent (anexar agente a chamada ao vivo)#

Entrega uma chamada ao vivo ao agente de voz IA. Corpo (opcional — cai para a config da instância quando vazio):

json
{ "system_prompt": "Você é a Bia...", "voice": "cedar", "initiate_first": true, "max_duration_seconds": 120 }

initiate_first:true faz o agente falar primeiro (saudação). Resposta 200: { "status": "attached", "instance_id": "...", "call_id": "..." }. 409 VOIP_AI_ALREADY_ATTACHED (um agente já está na chamada), 503 VOIP_AI_DISABLED, 502 VOIP_AI_ATTACH_FAILED.