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,.oggou.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]

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

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]


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):
- Preencha o Texto do Áudio com a frase exata que será falada.
- 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". - 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. - 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.shnormaliza via ffmpeg). TTS/upload salvam o arquivo no volumefreeswitch/sounds/announcementscom 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).
- Dispare uma chamada de teste que caia na causa do anúncio (ex. perfil com
media_treatment_mode = audio+ cenário sem saldo paranocredit). - Ouça: o anúncio deve tocar e a chamada encerrar normalmente.
- 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áINVITEcom R-URI*an-<code>. - 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.