Voz no perfil do usuário

O que é

A seção Voz no perfil do User é onde mora a capacidade SIP necessária para usar o softphone WebRTC embarcado no dashboard. Cada credencial de Voz corresponde a um endpoint registrável no Asterisk — um User pode ter zero, uma ou várias credenciais (uma por dispositivo, por exemplo: “laptop” e “celular”).

Esta página descreve o paradigma atualizado pela decisão D11 do ADR do Interaflow: Voz é capacidade do User, não do Atendente. O modelo legado “Atendente = um ramal SIP fixo” foi substituído por três camadas separadas:

User · VoiceCredential (0..N) · DialShortcut (0..1, opcional)

Quem nasce com Voz, quem precisa habilitar

Esta política reflete o uso real: a maioria dos Atendentes precisa de voz desde o dia 1; admins e supervisores só atendem ocasionalmente — não vale a pena gerar credencial para todos.

Estrutura da credencial

Cada credencial tem:

• Endpoint identifier — string alfanumérica única globalmente, no formato <prefixo_papel>_<slug>_<uuid_curto> (ex.: adm_eduardo_a3f9). É o identificador SIP usado no Asterisk (PJSIP). Estável — não muda quando você gera nova senha.
• Senha SIP — armazenada criptografada no banco (Fernet). Só é descriptografada em dois pontos: na geração do dialplan Asterisk, e quando o cliente WebRTC consulta para registro. Nunca é exibida na UI ou em logs.
• Estado — active (registra no Asterisk e funciona) ou archived (não gera mais endpoint PJSIP, mas histórico de CDR preservado).
• Device label — rótulo livre para o User identificar o dispositivo (“laptop”, “celular pessoal”, “headset recepção”). Útil quando há múltiplas credenciais.

Multi-device por desenho

Um User pode ter várias credenciais ativas ao mesmo tempo — cada dispositivo registra com endpoint identifier diferente. Cenários típicos:

• Atendente que trabalha em casa e no escritório com setups distintos, sem interferência.
• Supervisor que precisa atender no celular sem deslogar do desktop.
• Backup de credencial — se uma para de funcionar, a outra continua.

Como o softphone obtém a senha

A senha SIP nunca aparece em tela ou em código fonte. O fluxo seguro:

1. Cliente WebRTC abre a tela de Comunicação.
2. Faz POST autenticado para /api/v1/voice-credentials/{id}/register-secret.
3. Backend valida a sessão, registra a chamada em audit log e devolve o segredo cifrado in-memory para o cliente.
4. Cliente registra-se no Asterisk via WSS.

Isso protege contra:

• Senha vazada em screenshot ou print do DOM.
• Senha vazada em log de proxy.
• Acesso não autorizado à credencial (cada solicitação é audit-logada).

Rotação de senha

Quando a credencial é comprometida (ou por política periódica), rotação manual via “Regenerar senha” no perfil:

1. Admin ou User dono da credencial clica em “Regenerar senha”.
2. Backend gera nova senha aleatória, criptografa, salva.
3. Endpoint identifier permanece o mesmo — apenas a senha muda.
4. A próxima conexão do cliente WebRTC pega o novo segredo automaticamente. Conexões abertas continuam até reauth.

Frequência recomendada: ao trocar de empregador, ao detectar uso indevido, ou conforme política de rotação da empresa.

Arquivar credencial

Quando o User não precisa mais da credencial (saiu da operação, trocou de função, perdeu o dispositivo associado), arquivar é o caminho correto:

• Estado vira archived.
• O endpoint deixa de aparecer no pjsip.conf gerado, então o softphone para de registrar.
• O histórico de CDR / billing permanece ligado à credencial arquivada — auditoria de chamadas antigas continua funcionando.
• O endpoint identifier não é reaproveitado — credencial nova ganha identifier novo.

Atalho dialável (raro, opt-in)

O DialShortcut é um atalho numérico opcional que mapeia um número curto (ex.: 2018) para uma credencial de Voz. Existe só quando algo externo precisa discar a credencial pelo número:

• PBX corporativo do cliente que disca por extensão numérica.
• Conferência por PIN que aceita só números.
• Gateway analógico legado.
• CDR/billing legado que correlaciona por ID numérico.

O softphone WebRTC do Interaflow não usa DialShortcut. Ele disca por endpoint_identifier alfanumérico direto. O atalho é exposição numérica externa, não parte essencial do fluxo.

Características:

• Faixa numérica parametrizada por tenant (default 20000-29999).
• Contexto Asterisk configurável (default internal).
• Não reaproveita — arquivar libera o slot para um shortcut novo, mas o número antigo não volta a apontar para o endpoint antigo.

WebRTC-only

A política do produto é WebRTC-only para credenciais de Voz. Não há suporte primário para hardphone físico (Yealink, Polycom, Cisco) ou softphone de terceiro (Linphone, Zoiper, Bria) consumindo a credencial.

Essa decisão simplifica:

• Segurança — único cliente confiável é o softphone embarcado.
• Suporte — equipe não vira help-desk de configuração de aparelho.
• Atualização — features novas saem direto para todos sem firmware ou app de terceiro.

Existe uma tabela phone_devices no schema reservada para futuro, mas vazia em produção. Não é caminho oficial.

Fluxo passo a passo — habilitar Voz para Admin

1. Admin abre o próprio perfil em Configurações → Perfil.
2. Vai à seção Voz.
3. Clica em Habilitar voz.
4. Sistema cria uma credencial com endpoint identifier adm_<slug>_<uuid>.
5. Admin abre a tela Equipe → Comunicação.
6. Cliente WebRTC busca o segredo via /register-secret, registra no Asterisk.
7. Softphone fica registered — pronto para receber e fazer chamadas.

Boas práticas

• Use device label. Quando o User tem mais de uma credencial, rótulo claro evita confusão.
• Arquive credenciais não usadas. Dispositivo perdido ou desligado = arquivar. Mantém o roster limpo.
• Rotacione senhas periodicamente. Não há rotação automática; inclua no checklist de segurança da operação.
• Não compartilhe credencial entre Users. Audit fica comprometido. Cada pessoa tem a sua.
• Limite atalhos numéricos ao mínimo necessário. Quanto mais shortcut configurado, maior a superfície de teste para conflitos.

Limites conhecidos

• WebRTC-only. Hardphone e softphone de terceiro não são caminho suportado.
• Sem MFA dedicado para registro SIP — a defesa é manter o segredo seguro (Fernet, audit-logged).
• Endpoint identifier não pode ser personalizado com nome bonito; o formato é fixo para garantir unicidade global.
• DialShortcut limitado a faixa numérica configurada. Faixas fora do range padrão exigem ajuste de tenant_voice_settings.
• Sem auto-rotação. Rotação é manual.

Erros comuns

• Esperar que o admin tenha softphone funcional automaticamente. Admin precisa habilitar Voz manualmente; comportamento intencional.
• Procurar a senha SIP na UI. Não está lá. Cliente WebRTC obtém via endpoint autenticado.
• Tentar reaproveitar endpoint identifier antigo após arquivar. Não dá — credencial nova gera identifier novo.
• Configurar DialShortcut esperando o softphone usar. O softphone disca por endpoint alfanumérico direto.
• Usar credencial em hardphone. Pode até funcionar, mas não é caminho suportado e perde garantia de comportamento estável.

Ver também

• Comunicação e softphone
• Equipes, Atendentes e Filas
• Usuários e papéis
• Acesso Mobile