# PABX Atendai — integração do WebPhone

## Integração de WebPhone em aplicações externas

Este capítulo explica o telefone publicado no PABX Atendai e entrega um exemplo adaptável, com as mesmas chamadas de biblioteca e contratos usados pelo painel. A interface de exemplo é simples; os controles e os eventos podem ser ligados aos componentes do seu CRM, React, Vue ou JavaScript puro. Contrato da API: 0.16.0. Dependências verificadas no package-lock.json em 14/10/2026; use npm ci no projeto existente para reproduzi-las.

### Captura de chamadas no telefone integrado

A credencial SIP legível T{empresa_id}_{sufixo} é usada por telefones SIP comuns. No navegador, continue usando usuario, senha, dominio e wss devolvidos por GET /webphone; o adaptador mantém a identidade WebRTC estável. Não construa o usuário do navegador a partir do número do ramal.

Quando a empresa habilitar captura, aceite no campo de número os códigos configurados nessa empresa. Os padrões são #0 para geral e #1 seguido de um ramal (exemplo #11002 para 1002). Administradores e integrações com ramais:ler consultam GET /empresa/telefonia; não fixe códigos na integração nem exija esse escopo de atendentes: POST /webphone/preparar valida a configuração atual para a sessão do ramal. Envie o texto completo a POST /webphone/preparar e então use ua.call(dados.numero, opcoes), com as mesmas opções de áudio das ligações normais. tipo=captura identifica essa preparação. Os exemplos abaixo já usam o número retornado sem remover os sinais #. Não envie o código por sendDTMF nem por originate/transfer. Trate CAPTURA_DESATIVADA, RAMAL_CAPTURA_INVALIDO, SEM_CHAMADA_PARA_CAPTURAR e CAPTURA_INDISPONIVEL exibindo a mensagem do servidor. O JsSIP normaliza # para %23 no usuário da URI SIP; mantenha o código original em ua.call, sem codificar a URI inteira. Telefones físicos que usam # como tecla de envio precisam permitir os códigos completos no plano de discagem do aparelho. O prefixo antigo ##0 só funciona se o administrador o configurar explicitamente em Ramais → Telefonia desta empresa. A consulta não reserva a chamada: o atendimento por outra pessoa pode fazer a captura falhar em seguida.

### Escolha o tipo de integração

| Objetivo | Caminho disponível | Onde passa o áudio |
| --- | --- | --- |
| Abrir o telefone pronto a partir de um CRM | Link para https://pabx.atendai.chat/webphone; login individual do atendente | Navegador do atendente e Asterisk |
| Botão de ligar usando telefone já conectado | Backend do CRM chama POST /chamadas/originate com Bearer | Ramal de origem e destino, ligados pelo Asterisk |
| Telefone dentro de uma interface própria | JsSIP, WebRTC e os adaptadores de sessão descritos aqui | Navegador da interface e Asterisk |

O link do WebPhone já funciona a partir de outro sistema. Não aceita login, senha, número de destino ou comando de ligação pela URL. A pessoa entra e digita o destino na tela. O endpoint originate toca primeiro o ramal; não abre o microfone do navegador da aplicação externa e não substitui ua.call().

```html
<a href="https://pabx.atendai.chat/webphone" target="_blank" rel="noopener">
  Abrir telefone da empresa
</a>
```

### Bibliotecas e responsabilidades da implementação

| Componente | Versão instalada | Como usamos |
| --- | --- | --- |
| JsSIP | 3.13.8; package.json permite ^3.10.1 | UA SIP, REGISTER, INVITE, respostas, sessões WebRTC, DTMF, hold e REFER |
| APIs nativas do navegador | Sem pacote npm | getUserMedia, RTCPeerConnection, MediaStream, elemento audio e AudioContext |
| esbuild | 0.25.12 | Empacota import JsSIP from 'jssip' e o código da interface em JavaScript para navegador |
| htmx.org | 2.0.11 | Infraestrutura do painel; não transporta SIP nem áudio e não é necessário no exemplo |
| Tailwind CSS | 4.3.3 | Compilação de estilos do painel; não controla as chamadas |
| Node.js | 22.23.3 | Ferramenta de compilação; não é o servidor de mídia |
| Playwright | 1.63.0 | Testes de registro, interface, chamadas e áudio entre navegadores |

No repositório, interface/telefone.js concentra o comportamento do telefone; interface/conexao-webphone.js supervisiona transporte e registro, com o relógio de interface/relogio-webphone.js. interface/aplicacao.js fornece o adaptador HTTP com sessão, CSRF, contexto do cliente e erro.codigo. src/Aplicacao/Http.php aplica as permissões; DialplanRouter resolve números/rotas; CapacidadeSaida consulta e reserva linhas; RealtimeProvisioner configura PJSIP e WebRTC. A compilação do painel é npm run construir; a do exemplo isolado está abaixo. Não copie o bundle inteiro do painel para outro sistema: compile o exemplo ou integre JsSIP nos componentes da sua aplicação.

### Conexões, autenticação e limites entre origens

Há três conexões diferentes. A API HTTPS entrega configuração e valida a discagem. O WebSocket SIP, wss://pabx.atendai.chat/ws, leva a sinalização SIP via Nginx até o PJSIP. O áudio segue por WebRTC/DTLS-SRTP entre navegador e Asterisk; não é transmitido pela API REST nem pelo WebSocket de eventos do painel.

```text
Aplicação do atendente -- HTTPS + sessão --> API: credencial do próprio ramal e preparação
Aplicação + JsSIP      -- WSS /ws + SIP --> Nginx: sessão --> Asterisk PJSIP
Navegador             == WebRTC/DTLS-SRTP/ICE == Asterisk == destino SIP/tronco
Backend do CRM        -- HTTPS + Bearer --> API: originate, histórico e webhooks
```

O login atual usa formulário POST /entrar, cookie atendai_sessao e CSRF. Não há login JSON, JWT, OAuth, token SIP temporário ou SDK de autenticação publicado. O cookie é Secure, HttpOnly e SameSite=Lax. GET /api/v1/webphone exige sessão autorizada e devolve a credencial SIP do ramal. O upgrade de /ws também depende da sessão: Nginx consulta internamente /autorizar-ws. Senha SIP correta sem essa sessão não basta para abrir o WebSocket.

Uma chave Bearer não substitui a sessão em /webphone e não autentica /ws. O construtor WebSocket do navegador não aceita um cabeçalho Authorization arbitrário; o JsSIP instalado usa new WebSocket(url, 'sip'). O WebSocket /eventos-ws e seu ticket de 30 segundos são outro serviço, destinado a eventos administrativos, não à sinalização de chamadas.

O exemplo abaixo pressupõe a mesma origem HTTPS do PABX e valores de sessão inseridos pelo servidor. Não funciona por simplesmente abrir um arquivo HTML local ou trocar a URL da API para o domínio do PABX em uma página de outro site. Não há CORS publicado para essa integração, cookies entre sites têm restrições, e o painel usa frame-ancestors 'none': o WebPhone pronto não pode ser colocado em iframe. Mesmo subdomínios diferentes são origens diferentes para fetch.

Para uma aplicação própria, há dois caminhos de implantação: hospedar a tela sob a origem autorizada, com o mesmo contexto autenticado; ou implementar um backend/proxy de integração que mantenha sessões individuais por usuário, autorize empresa/ramal no servidor e autentique também o upgrade WSS. Esse segundo caminho exige implementação e homologação específicas; não existe um endpoint pronto de bootstrap externo nesta versão. Não use uma sessão de administrador compartilhada, não libere CORS com credenciais para qualquer origem e não remova /autorizar-ws para fazer o exemplo conectar. Em um proxy novo, valide a origem do navegador, preserve o subprotocolo sip e não exponha os serviços internos AMI/ARI/Asterisk HTTP.

### Preparação do usuário e contratos utilizados

Crie o ramal com webphone:true e, para chamadas à operadora, externas:true. Cadastre o acesso individual em Ramais → Acesso WebPhone. A conta de atendente recebe seu ramal fixo e conectar_automaticamente:true; passar outro ramal_id na URL não autoriza trocar de ramal. Administradores podem selecionar um ramal ativo da empresa em gestão. A senha de login do usuário é diferente da senha SIP e nunca deve ser usada como password do JsSIP.

| Operação relativa a /api/v1 | Uso pelo navegador | Contrato relevante |
| --- | --- | --- |
| GET /webphone?ramal_id=UUID | Obtém a identidade WebRTC autorizada | dados: ramal_id, numero, usuario, senha, dominio, wss |
| POST /webphone/preparar | Valida número, permissão, rota e capacidade | Corpo: ramal_id e numero; dados: numero, numero_enviado, tipo, destino |
| GET /webphone/filas?ramal_id=UUID | Lista as filas do próprio atendente | dados: lista com id, nome, ramal_id e pausado |
| POST /filas/UUID/disponibilidade | Pausa/retoma o próprio ramal | Corpo: ramal_id e pausado; motivo opcional; permissão operar_filas |

Todas usam a sessão do usuário. Para mutações, envie X-CSRF-Token. X-Empresa-ID confere o cliente já selecionado; não muda o cliente. O JSON usa sucesso/dados ou sucesso:false/erro. Em 401, refaça o login; em CSRF_INVALIDO ou CONTEXTO_ALTERADO, recarregue o contexto antes de repetir. Nunca capture o corpo de /webphone em logs, analytics ou ferramentas de erro.

Resposta ilustrativa de GET /webphone, com valores fictícios:

```json
{"sucesso":true,"dados":{"ramal_id":"00000000-0000-4000-8000-000000000001","numero":"101","usuario":"t123-e00000000000040008000000000000001","senha":"CREDENCIAL_SIP_SOMENTE_EM_MEMORIA","dominio":"empresa.exemplo.com","wss":"wss://pabx.atendai.chat/ws"}}
```

Use exatamente usuario/dominio/wss retornados. O usuário WebRTC não é o login web nem o número 101, e é diferente do usuário do telefone SIP UDP. Não chame /credencial para conectar: esse endpoint troca a senha e afeta outros dispositivos. A UA precisa manter material de autenticação enquanto estiver em uso; apagar acesso.senha depois da construção apenas evita uma cópia adicional, não elimina a credencial de dentro do JsSIP.

### cURLs para preparar e diagnosticar sem discar

Autentique conforme a seção API de sessão e administração do [guia completo](/documentacao/api). Estes comandos pressupõem sessao.txt, CSRF, EMPRESA_ID e RAMAL_ID já obtidos no contexto correto. Não coloque a chave Bearer em nenhum desses comandos de sessão.

```bash
BASE='https://pabx.atendai.chat/api/v1'
curl --fail-with-body --silent --show-error -b sessao.txt \
  -H "X-Empresa-ID: $EMPRESA_ID" "$BASE/webphone?ramal_id=$RAMAL_ID" \
  | jq 'if .dados then .dados |= del(.senha) else . end'

curl --fail-with-body --silent --show-error -X POST -b sessao.txt \
  -H "X-CSRF-Token: $CSRF" -H "X-Empresa-ID: $EMPRESA_ID" \
  -H 'Content-Type: application/json' "$BASE/webphone/preparar" \
  --data "{\"ramal_id\":\"$RAMAL_ID\",\"numero\":\"102\"}"
```

Preparar não inicia uma chamada nem reserva uma linha. Use dados.numero em ua.call(); numero_enviado serve para diagnóstico. Discar numero_enviado aplicaria a transformação da rota novamente. LINHAS_OCUPADAS/409 pede aviso e nova tentativa manual, sem retentativa automática. Se a capacidade acabar depois da preparação, o SIP retorna ocupado e a aplicação trata failed/Busy/486.

### Montar e compilar o exemplo

Salve os cinco arquivos na mesma pasta: [webphone.html](/documentacao/exemplo-webphone.html), [webphone.js](/documentacao/exemplo-webphone.js), [conexao-webphone.js](/documentacao/conexao-webphone.js), [relogio-webphone.js](/documentacao/relogio-webphone.js) e [correlacao-webphone.js](/documentacao/correlacao-webphone.js). Os blocos completos estão abaixo. O HTML entregue como exemplo não contém sessão válida; antes de servir a tela, o seu backend deve autenticar a pessoa e preencher CSRF_DA_SESSAO_AUTENTICADA, ID_DA_EMPRESA_DA_SESSAO e UUID_DO_RAMAL_AUTORIZADO usando os valores do contexto autorizado, escapados para HTML. Não receba esses valores como autorização de um parâmetro arbitrário do navegador.

```bash
mkdir exemplo-webphone
cd exemplo-webphone
npm init -y
npm install --save-exact jssip@3.13.8
npm install --save-dev --save-exact esbuild@0.25.12
# Depois de salvar os quatro arquivos nesta pasta:
npx esbuild webphone.js --bundle --minify --outfile=webphone-compilado.js
```

Sirva o HTML autenticado, webphone-compilado.js e relogio-webphone.js em HTTPS sob a origem configurada para a integração. O exemplo busca o relógio em /relogio-webphone.js; ajuste urlRelogio se usar outro caminho, com Content-Type de JavaScript e CSP permitindo worker-src 'self'. O arquivo baixado da documentação é um anexo de texto para copiar, não uma URL de execução. O PABX atual não instala automaticamente essa página personalizada. Para desenvolvimento, localhost permite algumas APIs de mídia, mas isso não fornece a sessão do PABX nem remove os requisitos de origem/WSS. Conserve o package-lock.json gerado e use npm ci nas compilações seguintes.

### Exemplo HTML do telefone

```html
<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <meta name="csrf-token" content="CSRF_DA_SESSAO_AUTENTICADA">
  <title>Exemplo de integração WebPhone</title>
</head>
<!-- O servidor preenche estes valores a partir do usuário autorizado. -->
<body data-empresa="ID_DA_EMPRESA_DA_SESSAO" data-ramal="UUID_DO_RAMAL_AUTORIZADO">
  <h1>Telefone da aplicação</h1>
  <p id="conexao" role="status">Desconectado</p>
  <button id="conectar" type="button">Conectar</button>
  <button id="ativar-audio" type="button">Ativar áudio e microfone</button>
  <p id="aviso-audio" role="status">Permita o microfone para conversar.</p>
  <p id="estado" role="status">Aguardando conexão</p>
  <p id="detalhe"></p><output id="duracao">00:00</output>
  <label>Número <input id="numero" type="tel" maxlength="30" autocomplete="off"></label>
  <button id="ligar" type="button" disabled>Ligar</button>
  <button id="atender" type="button" disabled>Atender</button>
  <button id="rejeitar" type="button" disabled>Rejeitar</button>
  <button id="encerrar" type="button" disabled>Encerrar</button>
  <button id="mudo" type="button" disabled>Mudo</button>
  <button id="espera" type="button" disabled>Espera</button>
  <label>Teclas DTMF <input id="digitos" maxlength="20" placeholder="123#"></label>
  <button id="enviar-dtmf" type="button" disabled>Enviar DTMF</button>
  <label>Transferir para o ramal <input id="ramal-transferencia" inputmode="numeric" maxlength="6"></label>
  <button id="transferir" type="button" disabled>Transferir</button>
  <audio id="audio-remoto" autoplay></audio>
  <script src="./webphone-compilado.js" defer></script>
</body>
</html>
```

### Exemplo JavaScript com JsSIP

O exemplo atende uma chamada por vez, rejeita a segunda com 486, trata autoplay, habilita áudio somente por gesto da pessoa, usa os mesmos eventos principais do painel e não armazena senhas em localStorage. Ajuste apresentação e acessibilidade aos componentes da sua aplicação. O código não liga automaticamente ao montar a página.

```javascript
import JsSIP from 'jssip';
import {acompanharConexao} from './conexao-webphone.js';
import {resolverCorrelacaoSip} from './correlacao-webphone.js';

// Adaptador para a sessão do PABX na mesma origem HTTPS.
const elemento=id=>document.getElementById(id);
const ramalId=document.body.dataset.ramal;
const csrf=document.querySelector('meta[name="csrf-token"]').content;
async function requisitar(caminho,corpo) {
  const resposta=await fetch('/api/v1'+caminho,{
    method:corpo===undefined?'GET':'POST',credentials:'same-origin',cache:'no-store',
    headers:{'Content-Type':'application/json','X-CSRF-Token':csrf,'X-Empresa-ID':document.body.dataset.empresa},
    ...(corpo===undefined?{}:{body:JSON.stringify(corpo)})
  });
  const resultado=await resposta.json();
  if(!resposta.ok || !resultado.sucesso){const falha=new Error(resultado.erro?.mensagem || 'Falha na API.');falha.codigo=resultado.erro?.codigo;throw falha;}
  return resultado.dados;
}

let agente,sessao,contextoAudio,pulsoToque,relogio,preparando=false,conectando=false;
let osciladores=[],pararSupervisao,retomarPagina=false,geracaoConexao=0;
const audio=elemento('audio-remoto');
const midia={mediaConstraints:{audio:true,video:false},pcConfig:{iceServers:[]}};
const mensagens={Busy:'A linha ou o destino está ocupado. Tente novamente em instantes.',
  'Not Found':'Destino não localizado. Confira o número e a rota.',Rejected:'Chamada recusada.',
  Unavailable:'Destino indisponível.', 'No Answer':'Ninguém atendeu.',Canceled:'Chamada cancelada.',
  'User Denied Media Access':'Permita o microfone.', 'WebRTC Error':'Não foi possível estabelecer o áudio.',
  'Authentication Error':'Registro recusado. Confira o acesso do ramal.',Terminated:'Chamada encerrada.'};

function atualizarBotoes(){
  const ativa=sessao && !sessao.isEnded(),atendida=ativa && sessao.isEstablished();
  elemento('conectar').disabled=Boolean(ativa || conectando);
  elemento('ligar').disabled=Boolean(navigator.onLine===false || !agente?.isRegistered() || ativa || preparando);
  elemento('atender').disabled=elemento('rejeitar').disabled=!(ativa && sessao.direction==='incoming' && !atendida);
  elemento('encerrar').disabled=!ativa;
  for(const id of ['mudo','espera','enviar-dtmf','transferir'])elemento(id).disabled=!atendida;
  elemento('mudo').textContent=sessao?.isMuted().audio?'Ativar microfone':'Mudo';
  elemento('espera').textContent=sessao?.isOnHold().local?'Retomar':'Espera';
}
function mostrar(estado,detalhe=''){elemento('estado').textContent=estado;elemento('detalhe').textContent=detalhe;atualizarBotoes();}
function pararToques(){clearInterval(pulsoToque);osciladores.forEach(tom=>{try{tom.stop();}catch{}});osciladores=[];}
function emitirTom(frequencia,inicio,duracao){
  if(contextoAudio?.state!=='running')return;
  const tom=contextoAudio.createOscillator(),ganho=contextoAudio.createGain();
  tom.frequency.value=frequencia;ganho.gain.value=.035;tom.connect(ganho);ganho.connect(contextoAudio.destination);
  tom.start(inicio);tom.stop(inicio+duracao);osciladores.push(tom);
  tom.onended=()=>{tom.disconnect();ganho.disconnect();osciladores=osciladores.filter(item=>item!==tom);};
}
function tocar(tipo){
  pararToques();
  const pulso=()=>{if(contextoAudio?.state!=='running')return;const agora=contextoAudio.currentTime;
    if(tipo==='entrada'){for(const deslocamento of [0,.5])for(const frequencia of [440,480])emitirTom(frequencia,agora+deslocamento,.35);}
    else if(tipo==='ocupado'){for(let i=0;i<4;i++)emitirTom(425,agora+i*.5,.25);}
    else emitirTom(425,agora,1);
  };pulso();if(tipo!=='ocupado')pulsoToque=setInterval(pulso,tipo==='entrada'?3000:5000);
}
async function ativarAudio(){
  contextoAudio ??= new AudioContext();await contextoAudio.resume();
  const fluxo=await navigator.mediaDevices.getUserMedia({audio:true});fluxo.getTracks().forEach(faixa=>faixa.stop());
  // JsSIP abrirá a mídia da chamada; esta captura apenas valida a permissão.
  elemento('aviso-audio').textContent='Áudio ativado. Pode trocar de aba; mantenha o WebPhone aberto e o computador ligado.';
  if(audio.srcObject)await audio.play();
}
async function conectar(){
  if(conectando || sessao && !sessao.isEnded())return;
  conectando=true;const geracao=++geracaoConexao;atualizarBotoes();
  try{
    const acesso=await requisitar('/webphone?ramal_id='+encodeURIComponent(ramalId));
    if(geracao!==geracaoConexao){delete acesso.senha;return;}
    pararSupervisao?.();
    if(agente){agente.removeAllListeners();agente.stop();}
    agente=new JsSIP.UA({sockets:[new JsSIP.WebSocketInterface(acesso.wss)],
      uri:`sip:${acesso.usuario}@${acesso.dominio}`,password:acesso.senha,...(acesso.contato_uri?{contact_uri:acesso.contato_uri}:{}),
      display_name:acesso.numero,register:true,register_expires:600,connection_recovery_min_interval:2,connection_recovery_max_interval:15,session_timers:false});
    delete acesso.senha; // UA mantém internamente o necessário para autenticar.
    agente.on('connecting',()=>{elemento('conexao').textContent='Conectando…';});
    agente.on('registered',()=>{elemento('conexao').textContent=`Ramal ${acesso.numero} conectado`;atualizarBotoes();});
    agente.on('unregistered',evento=>{if(!evento.cause)elemento('conexao').textContent='Ramal desconectado';atualizarBotoes();});
    agente.on('disconnected',()=>{elemento('conexao').textContent='Conexão SIP perdida; reconectando…';atualizarBotoes();});
    pararSupervisao=acompanharConexao(agente,{urlRelogio:'/relogio-webphone.js',
      aoRetomar:()=>{elemento('conexao').textContent=`Ramal ${acesso.numero} conectado`;atualizarBotoes();},
      aoFalhar:({temporario,espera})=>{
        elemento('conexao').textContent=temporario?'Reconectando…':'Registro recusado';
        if(!sessao||sessao.isEnded())mostrar('Falha no registro',temporario?`Nova tentativa automática em cerca de ${espera} segundos.`:'Confira o acesso e reconecte o ramal.');
      }});
    agente.on('newRTCSession',novaSessao);agente.start();
  }finally{if(geracao===geracaoConexao){conectando=false;atualizarBotoes();}}
}
function novaSessao(evento){
  if(sessao && !sessao.isEnded()){evento.session.terminate({status_code:486});return;}
  sessao=evento.session;const atual=sessao,recebida=evento.originator==='remote';let terminou=false;
  // Capture o Call-ID público do evento, mantendo o vínculo com esta sessão específica.
  const sipCallId=evento.request.getHeader('Call-ID');
  const correlacionar=()=>resolverCorrelacaoSip(requisitar,ramalId,sipCallId).then(dados=>{
    atual.data.correlacao_pabx=dados;
    document.dispatchEvent(new CustomEvent('pabx:correlacao',{detail:{sessao:atual,dados}}));
  }).catch(erro=>document.dispatchEvent(new CustomEvent('pabx:correlacao-pendente',{detail:{sessao:atual,codigo:erro.codigo||'CORRELACAO_INDISPONIVEL'}})));
  void correlacionar();
  clearInterval(relogio);relogio=null;elemento('duracao').textContent='00:00';
  mostrar(recebida?'Ligação recebida':'Ligando…',atual.remote_identity.uri.user);
  if(recebida)tocar('entrada');
  const conectarMidia=conexao=>conexao.addEventListener('track',eventoAudio=>{
    audio.srcObject=eventoAudio.streams[0] || new MediaStream([eventoAudio.track]);
    audio.play().catch(()=>{elemento('aviso-audio').textContent='Clique em Ativar áudio e microfone para ouvir.';});
  });
  if(atual.connection)conectarMidia(atual.connection);else atual.on('peerconnection',eventoConexao=>conectarMidia(eventoConexao.peerconnection));
  atual.on('progress',progresso=>{
    if(recebida)return;
    if(progresso.response?.status_code===183 && progresso.response.body){pararToques();mostrar('Conectando chamada','A operadora está enviando áudio.');}
    else{mostrar('Chamando…','Aguardando atendimento');tocar('saida');}
  });
  const atendida=()=>{pararToques();mostrar('Em ligação');if(!relogio){const inicio=Date.now();relogio=setInterval(()=>{const segundos=Math.floor((Date.now()-inicio)/1000);elemento('duracao').textContent=String(Math.floor(segundos/60)).padStart(2,'0')+':'+String(segundos%60).padStart(2,'0');},1000);}};
  atual.on('accepted',atendida);atual.on('confirmed',atendida);
  for(const nome of ['muted','unmuted','hold','unhold'])atual.on(nome,atualizarBotoes);
  const finalizar=fim=>{if(terminou)return;terminou=true;void correlacionar();pararToques();clearInterval(relogio);relogio=null;audio.srcObject=null;
    const ocupado=fim.cause==='Busy' || fim.message?.status_code===486;
    mostrar(ocupado?'Linha ocupada':'Ligação encerrada',mensagens[fim.cause] || 'Consulte o histórico para mais detalhes.');if(ocupado)tocar('ocupado');
  };atual.on('failed',finalizar);atual.on('ended',finalizar);
}
async function ligar(){
  if(preparando || sessao && !sessao.isEnded())return;
  preparando=true;atualizarBotoes();
  try{
    if(!agente?.isRegistered())throw new Error('Conecte o ramal antes de ligar.');
    pararToques();await ativarAudio();
    const destino=await requisitar('/webphone/preparar',{ramal_id:ramalId,numero:elemento('numero').value});
    // numero_enviado é apenas diagnóstico. O dialplan aplica a rota uma única vez.
    agente.call(destino.numero,midia);
  }catch(falha){mostrar(falha.codigo==='LINHAS_OCUPADAS'?'Linhas ocupadas':'Não foi possível ligar',falha.message);if(falha.codigo==='LINHAS_OCUPADAS')tocar('ocupado');}
  finally{preparando=false;atualizarBotoes();}
}
function aoClicar(id,acao){elemento(id).onclick=async()=>{try{await acao();}catch(falha){mostrar('Verifique a operação',falha.message);}};}
aoClicar('conectar',conectar);aoClicar('ativar-audio',ativarAudio);aoClicar('ligar',ligar);
aoClicar('atender',async()=>{await ativarAudio();if(sessao && !sessao.isEnded()){pararToques();sessao.answer(midia);}});
aoClicar('rejeitar',()=>sessao?.terminate({status_code:486}));aoClicar('encerrar',()=>sessao?.terminate());
aoClicar('mudo',()=>{if(sessao?.isEstablished())sessao.isMuted().audio?sessao.unmute({audio:true}):sessao.mute({audio:true});});
aoClicar('espera',()=>{if(sessao?.isEstablished()){const aceito=sessao.isOnHold().local?sessao.unhold():sessao.hold();if(aceito===false)throw new Error('Aguarde a negociação anterior e tente novamente.');}});
aoClicar('enviar-dtmf',()=>{const digitos=elemento('digitos').value;if(!/^[0-9*#]{1,20}$/.test(digitos))throw new Error('Use somente 0 a 9, * e #.');if(sessao?.isEstablished())sessao.sendDTMF(digitos);});
aoClicar('transferir',()=>{
  const destino=elemento('ramal-transferencia').value;if(!/^[0-9]{2,6}$/.test(destino))throw new Error('Informe um ramal da mesma empresa.');
  if(!sessao?.isEstablished())return;const origem=sessao;
  origem.refer(destino,{eventHandlers:{accepted:()=>{mostrar('Transferência aceita','Isso não comprova atendimento no destino.');if(!origem.isEnded())origem.terminate();},failed:()=>mostrar('Transferência falhou'),requestFailed:()=>mostrar('Transferência recusada')}});
});
window.addEventListener('pagehide',()=>{retomarPagina=Boolean(agente||conectando);geracaoConexao++;conectando=false;pararSupervisao?.();pararToques();clearInterval(relogio);relogio=null;agente?.stop();contextoAudio?.close();contextoAudio=null;});
window.addEventListener('pageshow',evento=>{if(evento.persisted&&retomarPagina){retomarPagina=false;conectar().catch(falha=>mostrar('Falha ao reconectar',falha.message));}});
window.addEventListener('offline',()=>{elemento('conexao').textContent='Sem conexão de rede';atualizarBotoes();});
atualizarBotoes();
// Para conectar ao montar a tela, chame conectar() uma única vez após o login.
// A permissão de áudio ainda depende da interação da pessoa com a página.
```

### Conexão em segundo plano e recuperação

Trocar de aba não deve encerrar a UA nem remover o registro. O painel e o exemplo usam o mesmo supervisor: um Web Worker emite um pulso a cada 10 segundos; a janela envia keepalive SIP CRLF a cada 20 segundos e antecipa a renovação do REGISTER a cada 120 segundos, solicitando validade de 600 segundos. O JsSIP continua processando OPTIONS, chamadas e sua própria renovação por registrationExpiring. Nenhuma credencial ou mídia é enviada ao Worker. A janela continua responsável pela sinalização; não se responde OPTIONS artificialmente para marcar como disponível um telefone incapaz de atender.

Falhas temporárias de REGISTER (timeout, conexão, SIP 408/480/5xx) recebem nova tentativa com espera progressiva de 15 a 120 segundos; Retry-After é respeitado até uma hora. Recusas permanentes de acesso exigem corrigir a configuração e reconectar. O transporte usa recuperação de 2 a 15 segundos. online, focus, visibilitychange visível, resume e pageshow verificam a conexão sem recriar a UA nem desligar a conversa. A página só chama stop() ao sair/fechar (pagehide), nunca em blur ou visibilitychange oculto. Se o navegador restaurar a página do cache de navegação, o telefone busca novamente a configuração autorizada e se conecta.

O Worker reduz a dependência dos temporizadores da aba, mas não impede suspensão ou descarte pelo navegador/sistema. Computador suspenso, navegador fechado, perda de rede ou aba descartada podem impedir o recebimento; voltar à página recupera o registro, não uma chamada já perdida. Para postos de atendimento, mantenha o computador acordado e adicione o domínio à lista de sites sempre ativos nas configurações de desempenho do Chrome/Edge se a economia de memória/energia suspender o WebPhone. Não mantenha o microfone aberto nem reproduza silêncio continuamente para contornar essas políticas. Referências: [temporizadores do Chrome](https://developer.chrome.com/blog/timer-throttling-in-chrome-88/), [ciclo de vida da página](https://developer.chrome.com/docs/web-platform/page-lifecycle-api).

O helper abaixo também pode ser usado num serviço estável de React/Vue. Chame acompanharConexao uma vez por UA, antes de start(), e guarde a função retornada para limpar Worker, listeners e timers antes de substituir/parar a UA. A opção aoFalhar informa temporario e espera em segundos; aoRetomar serve para atualizar o indicador a partir do estado registrado do JsSIP. Não habilite chamadas apenas porque o WSS abriu.

```javascript
// Supervisão do JsSIP sem recriar a UA ou encerrar sessões em andamento.
export function acompanharConexao(agente,{urlRelogio='/recursos/relogio-webphone.js',aoFalhar=()=>{},aoRetomar=()=>{}}={}) {
  let encerrado=false,bloqueado=false,proximoRegistro=Date.now()+120000,permitidoApos=0,ultimoPulso=Date.now(),ultimoKeepAlive=0,tentativas=0;
  let trabalhador,temporizador;
  const eventos=[];
  const escutar=(alvo,nome,funcao)=>{alvo.addEventListener(nome,funcao);eventos.push(()=>alvo.removeEventListener(nome,funcao));};
  const observar=(nome,funcao)=>{agente.on(nome,funcao);eventos.push(()=>agente.removeListener(nome,funcao));};
  function registrar() {
    if(encerrado || bloqueado || Date.now()<permitidoApos || navigator.onLine===false || !agente.isConnected())return;
    proximoRegistro=Date.now()+120000;
    agente.register(); // O próprio JsSIP impede REGISTERs simultâneos.
  }
  function verificar(retomando=false) {
    if(encerrado || navigator.onLine===false || bloqueado)return;
    const agora=Date.now(),atrasado=agora-ultimoPulso>45000;ultimoPulso=agora;
    if(!agente.isConnected()) {
      // connect é idempotente, inclusive enquanto há handshake/recovery pendente.
      agente.transport.connect();return;
    }
    if(agora-ultimoKeepAlive>=20000) {
      ultimoKeepAlive=agora;agente.transport.send('\r\n\r\n');
    }
    if(agora>=proximoRegistro || ((retomando || atrasado) && proximoRegistro-agora<115000))registrar();
  }
  observar('registered',()=>{bloqueado=false;tentativas=0;proximoRegistro=Date.now()+120000;aoRetomar();});
  observar('registrationExpiring',registrar);
  observar('registrationFailed',evento=>{
    const codigo=evento.response?.status_code;
    const temporario=evento.cause==='Connection Error' || evento.cause==='Request Timeout' || codigo===408 || codigo===480 || (codigo>=500 && codigo<600);
    bloqueado=!temporario;
    const retryAfter=Number.parseInt(evento.response?.getHeader?.('Retry-After'),10);
    const espera=Math.max(Math.min(120,15*2**Math.min(tentativas++,3)),Number.isFinite(retryAfter)?Math.min(3600,Math.max(0,retryAfter)):0);
    permitidoApos=proximoRegistro=Date.now()+espera*1000;
    aoFalhar({temporario,espera});
  });
  observar('unregistered',()=>{if(!bloqueado)proximoRegistro=Math.min(proximoRegistro,Date.now()+15000);});
  const retomar=()=>{verificar(true);if(!encerrado && navigator.onLine!==false && agente.isRegistered())aoRetomar();};
  escutar(window,'online',retomar);
  escutar(window,'pageshow',retomar);
  escutar(window,'focus',retomar);
  escutar(document,'resume',retomar);
  escutar(document,'visibilitychange',()=>{if(document.visibilityState==='visible')retomar();});
  function usarTemporizador() {
    if(encerrado)return;
    trabalhador?.terminate();trabalhador=null;
    temporizador ??= setInterval(()=>verificar(),10000);
  }
  try {
    trabalhador=new Worker(urlRelogio);
    trabalhador.onmessage=()=>verificar();
    trabalhador.onerror=evento=>{evento.preventDefault();usarTemporizador();};
  }catch{usarTemporizador();}
  return ()=>{
    if(encerrado)return;encerrado=true;
    trabalhador?.terminate();clearInterval(temporizador);eventos.forEach(remover=>remover());
  };
}
```

Arquivo relogio-webphone.js, servido como JavaScript na mesma origem:

```javascript
// Relógio independente dos timers da janela. Não recebe credenciais nem áudio.
setInterval(()=>postMessage('pulso'),10000);
```

Para homologar em um servidor preparado, execute os comandos abaixo. O cenário cria uma empresa temporária e dois ramais sem rotas externas. O teste com janela requer Chromium do Playwright e xvfb; não ativa flags que desabilitam a limitação de timers e usa connectOverCDP com noDefaults para impedir foco artificial. Confira document.visibilityState=hidden, OPTIONS reais e recebimento de chamadas antes de concluir que o segundo plano funciona. O segundo comando de navegador injeta uma única resposta SIP 503 no teste e valida recuperação, queda de WSS e retorno da rede. Finalize o cenário mesmo se um teste falhar.

```bash
node testes/conexao-webphone.cjs
php testes/webphone-segundo-plano-cenario.php preparar
MINUTOS_TESTE=7 xvfb-run -a node testes/webphone-segundo-plano.cjs
MINUTOS_TESTE=0 xvfb-run -a node testes/webphone-segundo-plano.cjs --recuperacao
php testes/webphone-segundo-plano-cenario.php finalizar
```

### Eventos e controles para reproduzir a experiência

| Evento/operação | Tratamento no PABX e no exemplo |
| --- | --- |
| UA registered | Habilitar Ligar; connected sozinho só confirma transporte, não registro SIP |
| UA disconnected / registrationFailed | Mostrar perda de conexão ou recusa; reconectar SIP não recupera automaticamente uma conversa perdida |
| newRTCSession | Criar estado da conversa, detectar entrada por originator=remote e preparar os listeners antes de atender |
| progress / 180 | Mostrar Chamando e gerar ringback local |
| progress / 183 com SDP | Parar ringback local para ouvir o áudio antecipado da telefonia |
| accepted / confirmed | Mostrar Em ligação; iniciar um único contador e parar o toque |
| failed / ended | Finalizar uma única vez, remover áudio/temporizadores e habilitar nova discagem |
| Busy ou SIP 486 | Aviso de linha/destino ocupado e quatro pulsos de 425 Hz |
| answer / terminate | Atender entrada; rejeitar, cancelar ou desligar conforme o estado da sessão |
| mute / unmute | Silenciar/restaurar o microfone, sem colocar a chamada em espera |
| hold / unhold | Negociar espera; tratar retorno false enquanto outra negociação está em andamento |
| sendDTMF | Enviar 0–9, * e # durante a conversa; com a biblioteca instalada o padrão é SIP INFO |
| refer | Transferência simples para ramal da mesma empresa; tratar accepted, failed e requestFailed |
| pagehide / desmontagem | Encerrar o agente e liberar tom, temporizadores, listeners e mídia conforme a política da aplicação |

O servidor anuncia RFC4733 para telefones SIP, mas o painel chama sendDTMF sem opções e o JsSIP 3.13.8 usa INFO por padrão. Não confunda o transporte de DTMF dos telefones UDP com o padrão desta biblioteca. Se optar por transportType:'RFC2833', homologue a negociação e o recebimento no seu fluxo antes de mudar. A transferência usa o contexto autorizado do PABX; não oferece transferência externa arbitrária ou transferência assistida/conferência no exemplo. O accepted do REFER é um sucesso de sinalização e não comprova conversa humana no destino.

Em React/Vue, mantenha uma única UA e a sessão em uma referência/serviço estável, fora das renderizações. Atualize os componentes pelos eventos, registre listeners uma única vez e remova-os na desmontagem. Não reconstrua a UA a cada alteração de estado. Se precisar manter a conversa ao trocar de rota, monte o telefone no nível da aplicação; desmontar e chamar stop() encerra sessões. Evite várias abas registrando o mesmo ramal sem uma política explícita.

### Filas, histórico e integração com o backend externo

Depois de registered, o painel consulta /webphone/filas. Para pausar, envie {ramal_id:UUID,pausado:true} para /filas/UUID/disponibilidade; false retoma. Atendentes só alteram sua própria participação. Ramal registrado não significa atendente livre: chamadas, pausa, descanso e reservas influenciam as filas e campanhas no servidor.

Uma aplicação externa que precisa apenas do botão Ligar pode usar o contrato abaixo em seu backend com chamadas:escrever. O navegador chama uma rota autenticada do próprio CRM; o CRM obtém o ramal permitido a partir do usuário, não confia em um ramal_id de outro cliente e mantém a chave Bearer no servidor. O áudio ocorre no ramal já conectado, inclusive no WebPhone aberto em outra aba.

```bash
curl --fail-with-body --silent --show-error -X POST "$BASE/chamadas/originate" \
  -H "Authorization: Bearer $CHAVE_API" -H "Idempotency-Key: $IDEMPOTENCIA" \
  -H 'Content-Type: application/json' \
  --data '{"ramal_id":"UUID_DO_RAMAL_AUTORIZADO","destino":"102"}'
```

Guarde a Idempotency-Key por ação e reutilize-a se houver timeout de rede. 202 não comprova atendimento. Acompanhe /chamadas/UUID com chamadas:ler ou eventos/webhooks conforme o guia. O id de JsSIP.RTCSession e o Call-ID SIP não são o UUID de app.chamadas: não os envie diretamente para /chamadas/UUID. Chamadas feitas com ua.call() não recebem esse UUID da preparação. Desde 0.19.0, resolva a sessão com POST /chamadas/correlacionar-sip, conforme o contrato abaixo. Não envie um UUID de chamada escolhido pelo cliente.

### Correlação exata entre WebPhone, atendimento do CRM e gravações (0.19.0)

Rota principal: **POST /api/v1/chamadas/correlacionar-sip**. O PABX persiste o vínculo observado entre cada diálogo SIP de um ramal e suas chamadas REST. A consulta não cria chamadas nem aceita que o navegador determine o UUID correspondente. Não use telefone, horário, Caller-ID, `RTCSession.id`, `linkedid` ou a chamada mais recente como substituto.

`POST /webphone/preparar` mantém exatamente sua função e resposta anteriores; `ua.call()` continua iniciando a chamada. Capture o Call-ID da requisição pública do evento `newRTCSession`, tanto para recebidas quanto realizadas:

```javascript
agente.on('newRTCSession', evento => {
  const sessaoDestaLigacao = evento.session;
  const sipCallId = evento.request.getHeader('Call-ID');
  // Vincule este identificador ao registro local desta sessão, não a uma variável
  // global de "último atendimento". O backend confirma a associação com o PABX.
  // Nunca use sessaoDestaLigacao.id como UUID REST.
});
```

Registre esse listener antes de `agente.start()`/`agente.call()`. Não leia propriedades privadas como `_request`. Preserve o Call-ID exatamente, inclusive maiúsculas e eventual `@`. O Call-ID do navegador e o da outra ponta podem ser diferentes: o PABX faz o vínculo por ramal e conexão observada, não presume uma identidade SIP única para toda a chamada.

No **backend do CRM**, use uma chave da empresa com `chamadas:ler`. O backend deve autenticar seu usuário, determinar o ramal permitido a partir do cadastro e validar o atendimento local que será atualizado. Informar `ramal_id` não autoriza o navegador a escolher outro atendente. Chaves API têm escopo de empresa e não identificam individualmente o usuário do CRM.

```bash
BASE=https://pabx.atendai.chat/api/v1
# CHAVE_API fica somente no servidor. RAMAL_ID é determinado pelo contexto autorizado.
# SIP_CALL_ID é o valor exato de evento.request.getHeader('Call-ID').
jq -n --arg ramal "$RAMAL_ID" --arg sip "$SIP_CALL_ID" \
  '{ramal_id:$ramal,sip_call_id:$sip}' |
  curl --silent --show-error --fail-with-body -X POST "$BASE/chamadas/correlacionar-sip" \
    -H "Authorization: Bearer $CHAVE_API" -H 'Content-Type: application/json' \
    --data-binary @-
```

Corpo: `sip_call_id` (obrigatório, 1–512 caracteres ASCII sem espaços) e `ramal_id` (UUID). Não envie `empresa_id`, `chamada_id` ou canais. A empresa vem da credencial. Sessões administrativas/supervisoras também podem consultar; uma sessão de **atendente** só pode consultar o próprio ramal vinculado e pode omitir `ramal_id`. POST com sessão exige CSRF. Não coloque Bearer no navegador nem crie um proxy CRM que aceite qualquer empresa/ramal do corpo sem autorização.

Resposta HTTP 200, exemplo fictício:

```json
{
  "sucesso": true,
  "dados": {
    "estado": "correlacionada",
    "sip_call_id": "exemplo-call-id@crm.example.invalid",
    "ramal_id": "00000000-0000-4000-8000-000000000001",
    "dialogo_id": "00000000-0000-4000-8000-000000000002",
    "chamadas": [{
      "chamada_id": "00000000-0000-4000-8000-000000000003",
      "chamada_pai_id": null,
      "chamada_raiz_id": "00000000-0000-4000-8000-000000000003",
      "ramal_id": "00000000-0000-4000-8000-000000000001",
      "estado": "bridged",
      "iniciada_em": "2026-10-28 13:00:00+00",
      "atendida_em": "2026-10-28 13:00:05+00",
      "encerrada_em": null,
      "participacao_id": "123",
      "numero_ramal": "101",
      "direcao": "recebida",
      "participacao_iniciada_em": "2026-10-28 13:00:02+00",
      "participacao_atendida_em": "2026-10-28 13:00:05+00",
      "participacao_encerrada_em": null
    }],
    "tentar_novamente_em_ms": null
  }
}
```

`dialogo_id` é a identidade persistente dessa conexão SIP no PABX; `chamada_id` é o UUID usado nos endpoints REST já existentes. `participacao_id` é texto e identifica o trecho de participação do ramal. Os timestamps de participação são observados no servidor e podem ser atualizados pelos eventos de telefonia. `atendida_em` da chamada pode indicar atendimento de uma URA/fila; para identificar atendimento humano daquele ramal, use `participacao_atendida_em`.

| Resposta | Tratamento |
|---|---|
| 200 / `correlacionada` | Persistir `dialogo_id` e **todos** os vínculos retornados, com atualização idempotente por atendimento local + diálogo + chamada + participação. |
| 202 / `pendente` | `dialogo_id:null`, `chamadas:[]`, `tentar_novamente_em_ms:1000` e cabeçalho `Retry-After: 1`. Repetir a cada segundo por até 30 segundos. |
| 403 | Falta de escopo/permissão. Não repetir automaticamente. |
| 404 | Ramal inexistente ou inacessível no contexto autenticado. Não tentar outra empresa. |
| 409 / `CORRELACAO_AMBIGUA` | Call-ID reutilizado em diálogos distintos do mesmo ramal ou identidade conflitante. Não selecionar um resultado arbitrário. |
| 409 / `CORRELACAO_COMPLEXA` | Cadeia de transferências cíclica/inválida ou acima do limite de 100 etapas. Não agrupar por aproximação. |
| 422 | Corpo ou Call-ID inválido. Corrigir a requisição. |

202 significa somente que o vínculo ainda não foi observado para aquele ramal. Pode permanecer pendente em tentativa que não chegou ao PABX, falha anterior à criação do CDR, Call-ID incorreto ou chamada antiga. Após o prazo, mantenha o registro local sem gravação associada e permita consultar novamente explicitamente. Não troque de Call-ID nem use telefone/horário como fallback. Um UUID resolvido não comprova atendimento nem gravação: consulte os estados.

#### Filas, transferências, vários dispositivos e captura

- Em fila ou toque simultâneo, cada conexão SIP recebe seu próprio `dialogo_id`, ligado ao mesmo UUID de chamada e ao ramal correspondente. O vínculo pode aparecer enquanto toca; participação sem `participacao_atendida_em` não significa conversa atendida.
- A transferência pela API conserva o UUID existente. O novo ramal recebe outro diálogo vinculado à mesma chamada.
- SIP/REFER pode criar outra chamada com `chamada_pai_id`; `chamada_raiz_id` permite agrupar a sequência sem usar canais internos. Um diálogo pode ter mais de um vínculo, por isso a resposta contém `chamadas`, não um UUID único sobrescrito.
- A resposta lista os vínculos **observados para o diálogo e ramal consultados**. Ela não concede acesso automático a todos os descendentes da raiz. Consulte a sessão de quem recebeu a transferência ou os webhooks v2 para as novas etapas. Uma chamada de consulta separada não deve ser agregada ao atendimento só porque ocorreu durante uma transferência; use apenas relações efetivamente registradas.
- A captura mantém a chamada original e vincula o diálogo do capturador. A autorização continua limitada à mesma empresa.
- Não alteramos o significado dos campos legados `ramal_id` e `ramal_atendimento_id` de `/chamadas/{id}`. Eles podem ser nulos e não substituem a participação específica retornada pela correlação.

#### Gravações e permissões

Depois de resolver, o backend usa **GET /chamadas/{chamada_id}/gravacoes**, com `gravacoes:ler`. Cada item inclui `id` da gravação, `chamada_id`, `ramal_id`, sentido e estado. Uma chamada pode ter várias gravações; não escolha automaticamente a primeira. Filtre pelo ramal/trecho autorizado para aquele atendimento. Para gravação `disponivel`, use **GET /gravacoes/{id}/arquivo**. Revalide a autorização do usuário do CRM ao reproduzir ou baixar; mantenha a chave no backend e entregue o áudio por uma rota autenticada do próprio CRM.

Atendentes podem resolver sua sessão, mas continuam **sem permissão para listar ou baixar gravações do cliente** diretamente. As permissões anteriores desses endpoints foram preservadas. A correlação, inclusive `chamada_raiz_id`, não é um token de acesso ao áudio.

A gravação é opcional. `gravando` indica metadados já criados e arquivo ainda não publicado; `disponivel` indica finalização e WAV validado; `sem_audio` e `falhou` não disponibilizam áudio. A resposta do arquivo continua validando estado e existência. Uma lista vazia não comprova, isoladamente, que jamais haverá gravação; confirme encerramento/estado e a configuração do ramal. O fim da chamada e o fim do processamento do áudio são momentos distintos.

#### Webhook v2 opcional, mantendo o v1

Em **Webhooks → Editar → Formato do webhook**, selecione a versão 2. Na API, envie `configuracao.versao_payload:"2"` no cadastro completo, preservando `versao`, URL e filtro de eventos. O padrão é `"1"`; webhooks existentes, inclusive os que recebem todos os eventos, continuam com o corpo v1. Omitir o novo campo num PUT mantém a versão já escolhida.

Assine pelo menos `gravacao.disponivel`, `gravacao.falhou`, `gravacao.sem_audio`, `call.created`, `call.completed` e `call.failed`, conforme a necessidade. Não precisa receber eventos novos: v2 acrescenta identificadores explícitos aos eventos existentes. Exemplo de `gravacao.disponivel`:

```json
{
  "versao": 2,
  "evento_id": "456",
  "chamada_id": "00000000-0000-4000-8000-000000000003",
  "chamada_pai_id": null,
  "chamada_raiz_id": "00000000-0000-4000-8000-000000000003",
  "gravacao_id": "00000000-0000-4000-8000-000000000004",
  "evento": "gravacao.disponivel",
  "empresa_id": 1,
  "dados": {"id":"00000000-0000-4000-8000-000000000004","duracao":12.5},
  "criado_em": "2026-10-28 13:00:18+00"
}
```

`gravacao_id` é nulo em outros tipos de evento; IDs de chamada/raiz são nulos quando o evento não corresponde a uma chamada. `dados` mantém seu formato anterior. Assinatura HMAC, cabeçalhos de entrega e política de retentativas permanecem os mesmos. Valide a assinatura sobre o corpo bruto recebido e deduplique por empresa + `evento_id`; não dependa da ordem de entrega. Webhooks são avisos: consulte a API para o estado atual e autorize o acesso ao atendimento no CRM. Mesmo em v2, o evento não contém o Call-ID SIP: a resolução da sessão é feita pela rota autenticada acima.

No CRM, a sequência é: registrar atendimento local e Call-ID da sessão → resolver no backend → persistir UUIDs autorizados → receber `gravacao.disponivel` v2 ou consultar depois → validar acesso ao atendimento → listar e reproduzir o trecho correto. O ID local do CRM nunca é usado diretamente na rota de gravações.

A correlação é garantida para os vínculos capturados após a instalação da versão 0.19.0. Não existe reconstrução retroativa segura por telefone/horário. O contrato não exige cabeçalhos SIP personalizados nem expõe senha, chave de API, canal Asterisk ou caminho de arquivo.

Arquivo auxiliar [correlacao-webphone.js](/documentacao/correlacao-webphone.js), usado pelo exemplo completo:

```javascript
/** requisitar usa a sessão autorizada ou o backend do CRM; nunca uma chave Bearer no navegador. */
export async function resolverCorrelacaoSip(requisitar,ramalId,sipCallId,{prazoMs=30000}={}) {
  if(typeof sipCallId!=='string'||!sipCallId)throw new Error('Call-ID SIP ausente.');
  const limite=Date.now()+Math.max(0,Math.min(30000,prazoMs));
  do {
    const resultado=await requisitar('/chamadas/correlacionar-sip',{ramal_id:ramalId,sip_call_id:sipCallId});
    if(resultado.estado==='correlacionada'&&resultado.chamadas?.length)return resultado;
    if(resultado.estado!=='pendente')throw new Error('Resposta de correlação inválida.');
    if(Date.now()>=limite)break;
    await new Promise(resolver=>setTimeout(resolver,Math.min(1000,limite-Date.now())));
  }while(Date.now()<=limite);
  const erro=new Error('Correlação ainda não disponível. Não associe por número ou horário.');
  erro.codigo='CORRELACAO_PENDENTE';throw erro;
}
```

O exemplo dispara `pabx:correlacao` com `{sessao,dados}` e salva a resposta em `sessao.data.correlacao_pabx`. No CRM, associe ao atendimento daquela sessão e confirme os dados no backend; não confie em UUIDs enviados pelo navegador como autorização. O evento `pabx:correlacao-pendente` inclui `sessao` e `codigo`, inclusive para falta de permissão ou ambiguidade; trate cada código sem fallback aproximado. Uma nova consulta é feita ao terminar a sessão. As consultas não interrompem o áudio. O `requisitar` do exemplo funciona sob a sessão HTTPS autorizada; uma aplicação em outra origem deve adaptar essa função para seu backend autenticado.

### Rede, privacidade e diagnóstico

O servidor usa WSS 443 e Asterisk Realtime/PJSIP com WebRTC, DTLS-SRTP, ICE e codecs alaw/ulaw. A faixa RTP configurada é UDP 10000–10199. O WebPhone atual usa iceServers:[]; não há TURN implantado. Isso não garante áudio em qualquer NAT, VPN ou rede corporativa. Para redes restritivas, a implantação de STUN/TURN e credenciais próprias deve ser planejada e homologada; não use servidores gratuitos aleatórios nem anuncie um TURN inexistente.

| Sintoma | O que conferir |
| --- | --- |
| HTTP 401/403 ao obter acesso | Sessão individual, troca inicial de senha, CSRF/perfil e ramal ativo habilitado para WebPhone |
| Falha ao abrir WSS | Cookie de sessão, /autorizar-ws, HTTPS/certificado, proxy Upgrade, subprotocolo sip e política do navegador |
| Transporte conectado, mas sem registro | Evento registrationFailed, identidade WebRTC devolvida pela API e autenticação PJSIP |
| Registrado sem toque ou som | Clique em Ativar áudio e microfone; confira permissão, saída de áudio, volume e autoplay |
| Atendeu, mas não há áudio | Faixas remotas, ICE/DTLS, NAT/firewall e pacotes WebRTC; registro SIP sozinho não comprova mídia |
| HTTP 409 LINHAS_OCUPADAS | Todos os troncos permitidos da rota atingiram capacidade; avisar e aguardar nova tentativa manual |
| Destino não localizado / SIP 404 | Número, DDD e transformação da rota; não confundir com falta de linhas |
| Chamadas duplicadas | Mais de uma UA/listener, duplo clique, múltiplas abas ou Idempotency-Key diferente em uma repetição |

Não coloque senha SIP, cookie, Bearer, SDP completo ou dumps de JsSIP em telemetria. A credencial SIP precisa chegar ao navegador autorizado, em HTTPS e somente em memória; não é uma credencial temporária. Desativação de usuário/sessão não deve ser descrita como hangup de uma conversa já estabelecida. Não exponha páginas de exemplo preenchidas com dados de um cliente como arquivos públicos estáticos.

Para validar uma integração, use ramais de homologação: registro, ligação entre dois navegadores, recebimento/toque, áudio nos dois sentidos, mudo, espera, DTMF na URA, transferência simples, cancelamento, ocupado, falta de microfone, expiração da sessão e reconexão. Teste também a rede real do atendente; testes no servidor não comprovam todos os cenários NAT. Só depois use um destino externo autorizado para verificar a rota da operadora.

### Validação do exemplo publicado

Em 08/10/2026, testes automatizados compilaram estes arquivos com JsSIP 3.13.8 e usaram dois navegadores de homologação contra a API e o WSS reais. Foram verificados registro, preparação, toque recebido, recusa SIP 486 com tom de ocupado, atendimento, pacotes WebRTC enviados/recebidos nos dois lados, mudo, espera/retomada, envio de DTMF por SIP INFO, transferência REFER para telefone SIP com RTP e encerramento. Os arquivos servidos por HTTPS coincidiram com as fontes documentadas.

O microfone dos testes usa áudio sintético do navegador; não houve chamada para operadora. Esse resultado comprova o exemplo na implantação e rede de homologação, sem garantir áudio em outras redes/NAT. O teste de DTMF confirma o envio de INFO; a escolha de teclas na URA da integração também deve ser homologada. No repositório, execute testes/documentacao.php e testes/webphone-documentacao.cjs conforme o procedimento de validação; o segundo exige o cenário isolado preparado e sua suspensão ao terminar.

### Referências técnicas consultadas

[JsSIP: UA e registro](https://jssip.net/documentation/3.10.x/api/ua/), [JsSIP: RTCSession e controles](https://jssip.net/documentation/3.10.x/api/session/), [Asterisk: clientes WebRTC](https://docs.asterisk.org/Configuration/WebRTC/Configuring-Asterisk-for-WebRTC-Clients/), [MDN: getUserMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) e [MDN: WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket/WebSocket). A versão instalada e os detalhes específicos do PABX foram conferidos no código e no package-lock.json, não presumidos a partir da versão mais recente da biblioteca.


### IP do navegador no registro

GET /webphone também retorna contato_uri. Passe esse valor ao parâmetro contact_uri do JsSIP.UA, como no exemplo. Ele correlaciona o Contact SIP ao IP da requisição HTTPS autenticada por até 24 horas. Não altere o valor nem use o identificador como credencial. A autenticação continua usando usuario e senha; contato_uri só permite mostrar a origem correta apesar do proxy. WebPhones antigos precisam reconectar. Uma mudança de rede também requer buscar novamente a configuração para atualizar a origem.
