Pular para o conteúdo principal

Configuração do Dialplan & Roteamento de Chamadas

📖 Voltar à Documentação Principal

Guia abrangente para configuração de dialplan XML, lógica de roteamento de chamadas e variáveis de dialplan.

Documentação Relacionada​

Documentação Principal​

Fluxo de Processamento de Chamadas​

Implementação de Serviços​

  • ⚙️ Serviços Suplementares - Implementação de encaminhamento de chamadas, bloqueio de CLI no dialplan
  • 📞 Correio de Voz - Roteamento de correio de voz e depósito/recuperação no dialplan
  • 🔊 Prompts TTS - Usando prompts no dialplan com reprodução

Monitoramento​

Configuração do Dialplan / Roteamento de Chamadas​

O TAS utiliza dialplans XML com um esquema compatível com formatos padrão de dialplan XML de telecomunicações, com variáveis populadas pelo TAS. Isso significa que você pode definir seu próprio dialplan conforme necessário, com a lógica de negócios para o operador, mas ter todos os dados necessários, como Dados do Repositório, informações de roteamento SS7, identidades IMPI / IMPU, normalização de dialplan, etc.

Dialplans são escritos em priv/templates e têm a forma:

  • mo_dialplan.xml - Dialplan de Chamadas Originadas por Móvel
  • mo_emergency_dialplan.xml - Dialplan de Chamadas de Emergência Originadas por Móvel
  • mt_dialplan.xml - Dialplan de Chamadas Terminadas por Móvel

Você pode visualizar os Dialplans a partir da interface Web.

Várias variáveis são definidas pelo TAS antes que o XML seja analisado, essas variáveis são impressas no log no início da chamada com seus valores atuais e são muito úteis ao definir sua própria lógica de chamadas.

Fundamentos do Dialplan XML do FreeSWITCH​

OmniTAS usa o mesmo sistema de roteamento de chamadas XML que o projeto FreeSWITCH, que permite um roteamento de chamadas flexível para atender às suas necessidades.

Esta seção explica os conceitos principais e fornece exemplos práticos.

Estrutura Básica​

Um dialplan consiste em extensões contendo condições e ações:

<extension name="descrição-do-que-isso-faz">
  <condition field="${variable}" expression="regex-pattern">
    <action application="app_name" data="parameters"/>
    <anti-action application="app_name" data="parameters"/>
  </condition>
</extension>

Extensões são avaliadas em ordem de cima para baixo. Quando uma condição corresponde, suas ações são executadas.

Condições e Correspondência Regex​

Condições testam variáveis contra expressões regulares. Se a regex corresponder, as ações são executadas; se não, as anti-ações são executadas.

Correspondência exata básica:

<condition field="${tas_destination_number}" expression="2222">
  <action application="log" data="INFO Chamando número de acesso ao correio de voz"/>
</condition>

Correspondência de múltiplos números:

<condition field="${tas_destination_number}" expression="^(2222|3444|3445)$">
  <action application="log" data="INFO Chamando serviço especial"/>
</condition>

Correspondência de padrão com grupos de captura:

<condition field="${tas_destination_number}" expression="^1(8[0-9]{9})$">
  <!-- Corresponde a 1 seguido de 8 e mais 9 dígitos -->
  <action application="log" data="INFO Correspondência de número gratuito: $1"/>
  <action application="bridge" data="sofia/gateway/trunk/${tas_destination_number}"/>
</condition>

Correspondência de prefixo:

<condition field="${tas_destination_number}" expression="^00">
  <!-- Corresponde a qualquer número que comece com 00 (internacional) -->
  <action application="log" data="INFO Chamada internacional detectada"/>
</condition>

Correspondência de intervalo:

<condition field="${msisdn}" expression="^5551241[0-9]{4}$">
  <!-- Corresponde a 55512410000 até 55512419999 -->
  <action application="log" data="INFO Assinante dentro do intervalo"/>
</condition>

Ações vs Anti-Ações​

Ações são executadas quando uma condição corresponde. Anti-ações são executadas quando uma condição NÃO corresponde.

<condition field="${cli_withheld}" expression="true">
  <!-- Executa se CLI estiver oculto -->
  <action application="set" data="effective_caller_id_number=anonymous"/>
  <action application="set" data="origination_privacy=hide_number"/>

  <!-- Executa se CLI NÃO estiver oculto -->
  <anti-action application="log" data="DEBUG CLI é normal"/>
  <anti-action application="set" data="effective_caller_id_number=${msisdn}"/>
</condition>

O Atributo continue="true"​

Por padrão, quando a condição de uma extensão corresponde, o dialplan para de processar extensões adicionais. O atributo continue="true" permite que o processamento continue para a próxima extensão.

Sem continue (comportamento padrão):

<extension name="First-Check">
  <condition field="${tas_destination_number}" expression="^(.*)$">
    <action application="log" data="INFO Processando chamada"/>
  </condition>
</extension>

<extension name="Never-Reached">
  <!-- Isso NUNCA é executado porque a extensão anterior correspondeu -->
  <condition field="${tas_destination_number}" expression="^(.*)$">
    <action application="log" data="INFO Isso não será impresso"/>
  </condition>
</extension>

Com continue="true":

<extension name="Print-Vars" continue="true">
  <condition field="${tas_destination_number}" expression="^(.*)$">
    <action application="info" data=""/>
  </condition>
</extension>

<extension name="Check-Balance" continue="true">
  <condition field="${hangup_case}" expression="OUTGOING_CALL_BARRED">
    <action application="log" data="ERROR Saldo insuficiente"/>
    <action application="hangup" data="${hangup_case}"/>
  </condition>
</extension>

<extension name="Route-Call">
  <!-- Esta extensão ainda é avaliada -->
  <condition field="${tas_destination_number}" expression="^(.*)$">
    <action application="bridge" data="sofia/gateway/trunk/${tas_destination_number}"/>
  </condition>
</extension>

Use continue="true" para:

  • Extensões de registro/debugging
  • Definir variáveis que se aplicam a múltiplos cenários
  • Verificações de validação que não roteiam a chamada

Aplicações Comuns​

controle de chamadas​

answer - Atender a chamada (enviar 200 OK)

<action application="answer" data=""/>

hangup - Encerrar a chamada com uma causa específica

<action application="hangup" data="NORMAL_CLEARING"/>
<action application="hangup" data="USER_BUSY"/>
<action application="hangup" data="NO_ANSWER"/>

bridge - Conectar a chamada a outro destino

<!-- Ponte para gateway externo -->
<action application="bridge" data="sofia/gateway/trunk/+12125551234"/>

<!-- Ponte para extensão interna com preferências de codec -->
<action application="bridge" data="{absolute_codec_string=AMR-WB,AMR,PCMA}sofia/internal/sip:user@domain.com"/>

<!-- Ponte com timeout -->
<action application="bridge" data="{originate_timeout=30}sofia/gateway/trunk/${tas_destination_number}"/>
Variáveis e Dados de Canal​

set - Definir uma variável de canal

<action application="set" data="my_variable=my_value"/>
<action application="set" data="sip_h_X-Custom-Header=CustomValue"/>
<action application="set" data="effective_caller_id_number=anonymous"/>

unset - Remover uma variável de canal

<action application="unset" data="sip_h_P-Asserted-Identity"/>

export - Definir variável e exportar para B-leg (chamada em ponte)

<action application="export" data="sip_h_X-Account-Code=ABC123"/>
Mídia e Prompts​

playback - Reproduzir um arquivo de áudio

<action application="playback" data="/sounds/en/us/callie/misc/8000/out_of_credit.wav"/>
<action application="playback" data="$${base_dir}/sounds/custom_prompt.wav"/>

sleep - Pausar por milissegundos especificados

<action application="sleep" data="1000"/>  <!-- Pausar por 1 segundo -->

echo - Ecoar áudio de volta para o chamador (teste)

<action application="echo" data=""/>

conference - Colocar a chamada em conferência

<action application="conference" data="room-${destination_number}@wideband"/>
correio de voz​

voicemail - Acessar o sistema de correio de voz

<!-- Deixar correio de voz para caixa de correio -->
<action application="voicemail" data="default default ${msisdn}"/>

<!-- Verificar correio de voz com autenticação -->
<action application="voicemail" data="check auth default default ${msisdn}"/>
Registro e Depuração​

log - Escrever no arquivo de log

<action application="log" data="INFO Processando chamada de ${msisdn}"/>
<action application="log" data="DEBUG Destino: ${tas_destination_number}"/>
<action application="log" data="ERROR Chamada falhou com causa: ${hangup_cause}"/>

info - Despejar todas as variáveis de canal no log

<action application="info" data=""/>
Aplicações Diversas​

say - Leitura de número em texto-para-fala

<action application="say" data="en number iterated ${tas_destination_number}"/>

send_dtmf - Enviar tons DTMF

<action application="send_dtmf" data="1234#"/>

Exemplos Práticos​

Roteamento de Serviços de Emergência:

<extension name="Emergency-911">
  <condition field="${tas_destination_number}" expression="^(911|112)$">
    <action application="log" data="ALERT Chamada de emergência de ${msisdn}"/>
    <action application="answer" data=""/>
    <action application="playback" data="/sounds/emergency_services_transfer.wav"/>
    <action application="bridge" data="sofia/gateway/emergency_gw/${tas_destination_number}"/>
  </condition>
</extension>

Roteamento Condicional Baseado em Saldo:

<extension name="Check-Credit">
  <condition field="${hangup_case}" expression="OUTGOING_CALL_BARRED">
    <action application="answer" data=""/>
    <action application="playback" data="/sounds/out_of_credit.wav"/>
    <action application="hangup" data="CALL_REJECTED"/>
  </condition>
</extension>

Roteamento On-Net vs Off-Net:

<extension name="Route-Decision">
  <condition field="${on_net_status}" expression="true">
    <!-- On-net: roteamento de volta através do TAS -->
    <action application="log" data="INFO Roteando para assinante on-net"/>
    <action application="bridge" data="sofia/internal/+${tas_destination_number}@10.179.3.60"/>
    <anti-action application="log" data="INFO Roteando off-net"/>
    <anti-action application="bridge" data="sofia/gateway/trunk/+${tas_destination_number}"/>
  </condition>
</extension>

Tratamento de ID do Chamador Anônimo:

<extension name="CLI-Privacy" continue="true">
  <condition field="${cli_withheld}" expression="true">
    <action application="set" data="effective_caller_id_name=anonymous"/>
    <action application="set" data="effective_caller_id_number=anonymous"/>
    <action application="set" data="origination_privacy=hide_number"/>
  </condition>
</extension>

Correio de Voz em Caso de Não Resposta:

<extension name="Try-Bridge-Then-VM">
  <condition field="${tas_destination_number}" expression="^(555124115\d{2})$">
    <action application="set" data="call_timeout=30"/>
    <action application="bridge" data="sofia/internal/${tas_destination_number}@domain.com"/>

    <!-- Se a ponte falhar, vá para o correio de voz -->
    <action application="log" data="INFO A ponte falhou, roteando para o correio de voz"/>
    <action application="answer" data=""/>
    <action application="voicemail" data="default default ${tas_destination_number}"/>
  </condition>
</extension>

Roteamento de Intervalo de Números:

<extension name="Local-Numbers">
  <condition field="${tas_destination_number}" expression="^([2-9]\d{2})$">
    <!-- Extensões locais de 3 dígitos 200-999 -->
    <action application="log" data="INFO Extensão local: $1"/>
    <action application="bridge" data="sofia/internal/$1@pbx.local"/>
  </condition>
</extension>

<extension name="National-Numbers">
  <condition field="${tas_destination_number}" expression="^555\d{7}$">
    <!-- Números móveis nacionais -->
    <action application="log" data="INFO Chamada móvel nacional"/>
    <action application="bridge" data="sofia/gateway/national_trunk/${tas_destination_number}"/>
  </condition>
</extension>

<extension name="International">
  <condition field="${tas_destination_number}" expression="^00\d+$">
    <!-- Chamadas internacionais começando com 00 -->
    <action application="log" data="INFO Chamada internacional"/>
    <action application="bridge" data="sofia/gateway/intl_trunk/${tas_destination_number}"/>
  </condition>
</extension>

Documentação Adicional​

Para detalhes completos sobre cada aplicação:

O wiki do FreeSWITCH contém documentação detalhada para cada aplicação de dialplan, incluindo todos os parâmetros e casos de uso.

Variáveis de Dialplan​

Variáveis definidas pelo TAS na lógica do dialplan XML:

Variáveis Comuns (Todos os Tipos de Chamadas)​

Configuração Inicial:

  • destination_number - número de destino traduzido
  • tas_destination_number - número de destino traduzido
  • effective_caller_id_number - número de origem traduzido

Chamadas de Emergência​

  • hangup_case - "none"
  • ims_private_identity - identidade de usuário privada
  • ims_public_identity - identidade de usuário pública
  • msisdn - número do assinante (sem o +)
  • imsi - IMSI da identidade privada
  • ims_domain - domínio da identidade privada

Chamadas MT (Terminadas por Móvel)​

  • ims_private_identity - identidade de usuário privada
  • ims_public_identity - identidade de usuário pública
  • msisdn - número do assinante (sem o +)
  • imsi - IMSI da identidade privada
  • ims_domain - domínio da identidade privada
  • call_forward_all_destination - destino CFA ou "none"
  • call_forward_not_reachable_destination - destino CFNRc
  • scscf_address - endereço S-CSCF ou "none"
  • scscf_domain - domínio S-CSCF ou "none"
  • no_reply_timer - timeout para nenhuma resposta
  • hangup_case - "none" ou "UNALLOCATED_NUMBER"
  • msrn - MSRN do PRN (se em roaming) ou número encaminhado do SRI (se o encaminhamento de chamadas estiver ativo)
  • tas_destination_number - Substituição de destino de roteamento (definido como MSRN ou número encaminhado)

Chamadas MO (Originadas por Móvel)​

  • hangup_case - "none", "OUTGOING_CALL_BARRED" ou "UNALLOCATED_NUMBER"
  • ims_private_identity - identidade de usuário privada
  • ims_public_identity - identidade de usuário pública
  • msisdn - número do assinante (sem o +)
  • imsi - IMSI da identidade privada
  • ims_domain - domínio da identidade privada
  • allocated_time - tempo alocado pelo OCS (se a cobrança online estiver habilitada)
  • cli_withheld - string "true" ou "false"
  • on_net_status - string "true" ou "false" (se o destino está on-net)
  • msrn - MSRN para assinantes em roaming (se aplicável)
  • tas_destination_number - substituição de MSRN (se em roaming)

Chamadas de Emergência​

Chamadas de emergência são controladas através do parâmetro de configuração emergency_call_codes e são automaticamente detectadas durante a autorização da chamada.

Configuração​

Configure os códigos de chamada de emergência no seu arquivo config/runtime.exs:

config :tas,
  emergency_call_codes: ["911", "912", "913", "sos"],
  # ... outras configurações

Detalhes da Configuração:

  • emergency_call_codes (obrigatório): Lista de strings representando números de serviço de emergência
  • Esses códigos são verificados além dos URNs de emergência SIP (por exemplo, <urn:service:sos>)
  • O sistema realiza uma comparação de correspondência exata contra o número de destino
  • Códigos comuns incluem: "911" (EUA), "112" (UE), "000" (AU), "999" (UK), "sos"

Como Funciona a Detecção de Emergência​

A função Tas.Dialplan.Authorization.is_emergency_call?/2 verifica duas condições:

  1. URN de Serviço de Emergência SIP URI: Detecta <urn:service:sos> ou qualquer URI contendo "service:sos"
  2. Correspondência de Número de Destino: Compara Caller-Destination-Number com os emergency_call_codes configurados

Se qualquer condição for verdadeira, a chamada é classificada como emergência.

Referência de Código: Veja lib/dialplan/authorization.ex

Fluxo de Processamento​

Detalhes do Fluxo de Chamadas:

  1. A chamada chega ao TAS
  2. O módulo de autorização verifica o destino contra padrões de emergência
  3. Se emergência detectada:
    • O tipo de chamada é definido como :emergency
    • O template mo_emergency_dialplan.xml é usado
    • A autorização OCS é tipicamente ignorada
    • A chamada é roteada para o gateway PSAP
  4. Métricas são registradas com o rótulo call_type: emergency

Roteamento do Dialplan​

Defina o roteamento para chamadas de emergência em priv/templates/mo_emergency_dialplan.xml. Este template determina como as chamadas são roteadas para seu PSAP (Ponto de Atendimento de Segurança Pública) ou URI SIP com base nos requisitos do seu mercado.

Exemplo de dialplan de emergência:

<extension name="Emergency-SOS">
  <condition field="${destination_number}" expression="^(911|912|913|sos)$">
    <action application="log" data="ALERT Chamada de emergência de ${msisdn}"/>
    <action application="answer" data=""/>
    <action application="bridge" data="sofia/gateway/psap_gw/${destination_number}"/>
  </condition>
</extension>

Melhores Práticas​

  • Sempre inclua "sos" na sua lista de códigos de emergência para compatibilidade com URN SIP
  • Inclua todos os números de emergência locais para sua jurisdição (por exemplo, 911, 112, 000, 999)
  • Teste o roteamento de emergência regularmente usando o Simulador de Chamadas
  • Ignorar OCS para chamadas de emergência para garantir que sempre se conectem (configurado via skipped_regex)
  • Configure o gateway PSAP com alta disponibilidade e redundância
  • Monitore as métricas de chamadas de emergência para garantir a confiabilidade do sistema

Chamada Originada por Móvel On-Net para um Assinante Terminando por Móvel On-Net​

Você pode roteá-la do seu dialplan para o seu dialplan através de algo como isto:

<action application="bridge" data="{absolute_codec_string=AMR-WB,AMR,PCMA,PCMU,originate_retries=1,originate_timeout=60,sip_invite_call_id=${sip_call_id}}sofia/internal/+${tas_destination_number}@10.179.3.60" />

Onde 10.179.3.60 é o IP do TAS (Está roteando a chamada de volta para o TAS) - Apenas certifique-se de que o IP do TAS esteja na sua lista allowed_sbc_source_ips.