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:
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:
{
"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.assignedfingerprint.rotatedwarmup.phase_changedwarmup.bypass_grantedwarmup.bypass_expiredconnection.openedconnection.closedconnection.bannedhygiene.appliedhumanize.appliedstealth.inbound_first.blockedstealth.app_version_canary_startedstealth.app_version_fleet_appliedstealth_transport.debug_enabledstealth_transport.debug_renewedstealth_transport.debug_expired
Notas warmup:
warmup.phase_changede gravado de forma transacional junto com oUPDATE tenant_instances.warmup_phase.warmup.bypass_grantede emitido pela ação superadmin de bypass de warmup e carregareason,ticket_id,tokeneexpires_atdentro deevent_data.hygiene.appliede emitido uma vez por alteração bem-sucedida (push_name,photo,status) e carregatype+valuedentro deevent_data.
Exemplo com curl:
curl -N \
-H "Authorization: Bearer eyJ..." \
"https://api.catcher.one/v1/instances/84c2e480/events?events=message.received,connection.update"
Exemplo com JavaScript (fetch streaming):
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:
{
"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:
{
"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
429antes do upgrade
Exemplo com Node.js (ws com headers):
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 (default50, máximo200)page— página 1-based (default1)
Resposta 200:
{
"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 eventocall.received)phone/from— identidade do chamador (phonevazio para LID/grupo); nunca URL de CDN da Metadirection— sempreinbound(ocall_logsregistra apenas OFFERs de entrada)status—offered|accepted|rejected|endedduration_seconds/media_id— duração real e gravação (via VoIP);nullquando a chamada não foi gravadatimestamp/accepted_at/ended_at/created_at— RFC3339 (UTC);nullquando ausente- Ordenado por
created_atdecrescente (mais recente primeiro).has_more=trueindica que há a próxima página.
Nota (linkage da gravação): o
media_id+duration_secondssão gravados na linhacall_logspelo worker no caminhocall.recorded(VoIP). Instâncias sem VoIP habilitado ou chamadas não atendidas ficam com esses camposnull.
Á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 ummedia_idda BiaZap; nunca uma URL de CDN da Meta. call.recordedé emitido normalmente ao encerrar, commedia_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:
{
"calls": [
{
"call_id": "AC354C9DCD3C31E4F280710749CBF5DA",
"phone": "554192464230",
"from": "554192464230@s.whatsapp.net",
"started_at": 1774725057
}
]
}
call_id— id da chamada do WhatsApp (o mesmo do eventocall.received)phone/from— identidade do chamador (BR-normalizada, LID→telefone resolvido); nunca uma URL de CDN da Metastarted_at— unix (segundos) de quando a chamada ficou ativa (mídia fluindo)- Ordenado por
started_atdecrescente (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
429antes 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 404quando ocallIDnão pertence à sua empresa;503quando 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:
{ "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 origemt0(o instante em que a API começou a transcrever a chamada) com o mesmo relógio, entãostart_msé comparável globalmente entre os speakers — ordenar porstart_msproduz a ordem cronológica correta mesmo intercalando caller e operator.is_final—truena v1 (segmentos completos; o campo deixa espaço para parciaisis_final:falsenuma 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):
// 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:
{
"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 porstart_mscrescente;[](nuncanull) 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:
{ "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:
{ "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:
{ "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 allowlistsVOIP_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:
{ "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):
{ "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.