Ir para o conteúdo

Roteiro: Criar anúncio completo (texto/TTS, áudio e fallback SIP)

Perfil necessário: admin | viewer (consulta) Menus usados: Plataforma, Sistema Risco: médio (anúncio é a "voz" da plataforma em falhas: code/reason errado confunde o cliente; para clientes com tratamento audio, um anúncio malformado afeta toda negação daquele perfil) Rollback: desligar o anúncio (Ativo = Inativo) — send_treatment só considera linhas enabled=1; ou corrigir os campos no mesmo dialog; exclusão pela lixeira (confirmação Excluir anúncio "<code>"?). Para desfazer um áudio, basta enviar outro arquivo (substitui o anterior).

Pré-requisitos

  • [ ] Pelo menos um Media Server ativo (página Infraestrutura → Media Servers) — sem ele, o tratamento cai no fallback SIP mesmo com o anúncio configurado
  • [ ] Para TTS: chave de API Minimax (conta em platform.minimax.io → Account → API Keys)
  • [ ] Para upload: arquivo .wav, .mp3, .ogg ou .opus
  • [ ] Perfil admin

Passo a passo

1. Abrir a página de anúncios

Caminho: Plataforma → Infraestrutura → Anúncios de Mídia Clique: [Novo Anúncio]

Lista de anúncios com o botão Novo Anúncio destacado

Colunas: Código (identificador lógico), R-URI, SIP (code do fallback), Reason, Áudio (botão de ouvir/pausar; ícone desabilitado quando não há áudio), Ativo.

O catálogo já vem semeado com os códigos padrão do domínio (nocredit, busy, noroute, congestion, collectblocked, ...) — veja a tabela no fim deste roteiro. Só crie um código novo quando a causa de negação não existir no catálogo.

Resultado esperado: listagem com os anúncios do ambiente e seus áudios.

2. Preencher o dialog Novo Anúncio

Caminho: Plataforma → Infraestrutura → Anúncios de Mídia Clique: [Novo Anúncio] → botão [Criar] no rodapé do dialog

Dialog Novo Anúncio aberto

Preencha:

Campo Obrig. Formato/exemplo Efeito
Código * sim nocredit (minúsculas, dígitos, _, -; imutável após criar) Identificador usado pelo send_treatment do OpenSIPS; também vira o nome do arquivo de áudio no MS
Serviço não tts, ivr (default generic) Rótulo enviado no header P-Service ao media server
Padrão R-URI * sim sip:*an-nocredit@media-server (convenção *an-<code>) R-URI enviada ao MS; o host media-server é reescrito para o MS ativo do dispatcher set 900
SIP Code (fallback) * sim inteiro 100–699 (ex. 402) Code do send_reply no modo signaling e quando o MS está indisponível
SIP Reason (fallback) * sim Payment Required Reason do fallback
Texto do Áudio não transcrição do locutor Fonte do TTS e documentação do prompt
Descrição não texto livre Contexto operacional
Ativo não (default Ativo) Ativo | Inativo Só linhas enabled=1 são lidas pelo OpenSIPS

Validação do formulário: código deve casar ^[a-z0-9_-]+$; R-URI e Reason obrigatórios; SIP Code entre 100 e 699.

Resultado esperado: toast "Anúncio criado"; linha nova na tabela com código, R-URI e SIP code.

3. Configurar o TTS (uma vez por ambiente)

Caminho: Plataforma → Infraestrutura → Anúncios de Mídia Clique: [Configurações TTS] (no cabeçalho da página) → [Salvar Configuração]

Botão Configurações TTS destacado no cabeçalho da página

Dialog Configurações TTS — Minimax

Preencha:

Campo Obrig. Formato/exemplo Efeito
Chave de API * sim (1ª vez) eyJ... (campo senha; deixe vazio para manter a atual) Credencial das chamadas de geração; exibida mascarada como ***<4 últimos>
Modelo não (default speech-02-hd) speech-02-hd | speech-02-turbo | speech-2.6-hd | ... HD = maior qualidade; Turbo = mais rápido
Velocidade não (default 1.0) 0.5 a 2.0 (passo 0.1) Ritmo da fala
Voice ID não Portuguese, Brazilian_Vivid_Lady (alt.: Portuguese, Brazilian_Natural_Man) Voz da síntese
Endpoint não default da API Minimax (api-uw.minimax.io tem menor latência p/ EUA) URL do serviço TTS

O rodapé do dialog mostra o status: API configurada (xxxx)* em verde ou Chave de API não configurada em amarelo.

Resultado esperado: card verde "API configurada".

4. Editar o anúncio: texto, TTS e áudio

Caminho: Plataforma → Infraestrutura → Anúncios de Mídia Clique: ícone Editar (lápis) na linha do anúncio

No dialog Editar Anúncio (o campo Código fica desabilitado):

  1. Preencha o Texto do Áudio com a frase exata que será falada.
  2. Clique: [Gerar com Minimax] (aparece ao lado do rótulo "Texto do Áudio" somente no modo edição; exige texto não vazio e chave de API configurada). O botão salva o texto atual e chama o Minimax; em sucesso aparece o player com o áudio gerado (.mp3) e o toast "Minimax TTS concluído com sucesso".
  3. Alternativa sem TTS: [Enviar Áudio] na seção Áudio abre o seletor de arquivos (.wav, .mp3, .ogg, .opus); com áudio existente o botão passa a se chamar [Substituir Áudio]. O upload substitui o arquivo anterior e o player recarrega.
  4. Ouça pelo player do dialog ou pelo botão de alto-falante na linha da tabela antes de considerar pronto.

Resultado esperado: coluna Áudio da linha com ícone habilitado (alto-falante); reprodução limpa em pt-BR.

Escala do áudio no FreeSWITCH: o dialplan do MS toca announcements/<code>.wav; os prompts do repositório são 8 kHz/16-bit/mono PCM (scripts/generate_announcements.sh normaliza via ffmpeg). TTS/upload salvam o arquivo no volume freeswitch/sounds/announcements com o nome do código — se o toque ficar distorcido ou o formato não for aceito pelo container, converta o arquivo para WAV 8 kHz mono PCM antes do upload.

5. Testar o anúncio de ponta a ponta

O caminho de execução é SIP, não HTTP: uma negação com media_treatment_mode = audio no perfil da linha faz o OpenSIPS reescrever a R-URI para *an-<code> e relaya ao MS do dispatcher set 900 (headers P-Announcement, P-Service, P-Cause).

  1. Dispare uma chamada de teste que caia na causa do anúncio (ex. perfil com media_treatment_mode = audio + cenário sem saldo para nocredit).
  2. Ouça: o anúncio deve tocar e a chamada encerrar normalmente.
  3. CDR → Fluxo em janela: o estágio MEDIA/falha mostra o tratamento aplicado (treatment_applied=1, code/reason do anúncio); na perna ao MS há INVITE com R-URI *an-<code>.
  4. Fallback SIP: com o MS indisponível (ex. container parado), a mesma chamada deve receber o SIP Code/Reason cadastrados em vez de tocar áudio.

Resultado esperado: áudio tocando no cenário normal; code/reason correto no cenário de fallback.

Validação

  • [ ] Visual: anúncio listado com Ativo = Sim e ícone de áudio habilitado.
  • [ ] Visual (TTS): card verde "API configurada (***xxxx)".
  • [ ] Funcional: player da tabela reproduz o áudio do anúncio.
  • [ ] Funcional: chamada de teste na causa correspondente ouve o anúncio (perfil audio) — conferir estágio MEDIA no Fluxo em janela do CDR.
  • [ ] Funcional: com o MS fora, o caller recebe o SIP Code/Reason cadastrados (fallback).
  • [ ] Arquivo: freeswitch/sounds/announcements/<code>.* existe no volume montado no container.

Erros comuns

Sintoma Causa provável Correção
"Código de anúncio já existe" (409) ao criar Código duplicado Usar o existente (editar) ou escolher outro código
Campo Código rejeitado Caracteres fora de [a-z0-9_-] ou maiúsculas Corrigir o código (ex. no-credit → nocredit)
Anúncio não toca; caller recebe só code/reason MS indisponível/inativo → fallback SIP Conferir Media Servers (Ativo) e dispatcher set 900
Anúncio não toca e recebe 503 Service Unavailable Código não existe ou Ativo = Inativo Ativar o anúncio ou criar com o código usado pela rota
Botão Gerar com Minimax desabilitado Campo Texto do Áudio vazio Preencher o texto antes
Erro TTS "Configure a chave de API Minimax antes de gerar" Chave ausente Configurações TTS → colar chave → Salvar Configuração
Erro TTS 502/504 ao gerar Chave/modelo/endpoint inválidos ou timeout da API Conferir chave e endpoint (api-uw.minimax.io); tentar modelo Turbo
Anúncio toca tom de reordem (440/480 Hz) em vez da voz Arquivo <code> ausente no volume do MS (dialplan cai no fallback) Gerar via TTS ou enviar o arquivo; conferir nome/extensão
Áudio distorcido/muito grave no toque Formato/taxa fora do padrão do MS Enviar WAV 8 kHz 16-bit mono PCM
Alteração no texto não surte efeito Texto alterado sem gerar áudio novo Após editar o texto, clicar Gerar com Minimax de novo
Mudança não aplicada nas negações Cache de anúncios do OpenSIPS (300s) Aguardar ~5 min ou reiniciar OpenSIPS em janela

Tabela de referência rápida

Campo/catálogo Valor Uso
busy 486 Busy Here destino ocupado/limite de canais
noroute 404 No outbound route sem rota de saída
notfound 404 Not Found número não localizado
unavailable 480 Temporarily Unavailable destino temporariamente indisponível
noanswer 408 No Answer não atendeu
invalidnumber 404 Invalid Number número inválido/blacklist
forbidden 403 Forbidden prefixo/ANI fora da ACL
blockedoutgoing 403 Outgoing Blocked saída bloqueada por política
blockedincoming 403 Incoming Blocked entrada bloqueada por política
noanonimity 433 Anonymity Disallowed chamada anônima não permitida
collectblocked 603 Collect Call Blocked chamada a cobrar bloqueada
nocredit 402 Payment Required sem saldo/crédito
norate 404 No Rate Available sem tarifa para o destino
noquota 403 Quota Exceeded quota excedida
congestion 503 Service Unavailable congestionamento/CPS/concorrência
outofhours 403 Out of Business Hours fora do horário de atendimento
notlocal 404 Not Local destino não é local
notlong 404 Not Long Distance destino não é LDN

Códigos SIP→anúncio resolvidos automaticamente pelo OpenSIPS em falha de carrier: 486/600→busy, 480/408→unavailable, 404→notfound, 403→forbidden, 484/485→invalidnumber, 5xx (500/502/503/504)→carrier_unavailable.