Configuración del Dialplan y Enrutamiento de Llamadas

📖 Volver a la Documentación Principal

Guía completa para la configuración del dialplan XML, lógica de enrutamiento de llamadas y variables del dialplan.

Documentación Relacionada

Documentación Principal

📋 README Principal - Descripción general y inicio rápido
🔧 Guía de Configuración - Configuración de troncos SIP y gateways
🔧 Guía de Operaciones - Pruebas de dialplan y visualizador de plantillas

Flujo de Procesamiento de Llamadas

🔢 Traducción de Números - Normalización E.164 (sucede antes del dialplan)
👥 Interfaz Sh - Datos del suscriptor recuperados para variables del dialplan
📡 SS7 MAP - Datos de MSRN/HLR en variables del dialplan
💳 Carga en Línea - Autorización OCS en el flujo de llamadas

Implementación de Servicios

⚙️ Servicios Suplementarios - Implementación de desvío de llamadas, bloqueo de CLI en el dialplan
📞 Buzón de Voz - Enrutamiento de buzón de voz y depósito/recuperación en el dialplan
🔊 Prompts TTS - Uso de prompts en el dialplan con reproducción

Monitoreo

📊 Métricas del Dialplan - Métricas específicas del dialplan y monitoreo
📈 Referencia de Métricas - Métricas generales del sistema

Configuración del Dialplan / Enrutamiento de Llamadas

El TAS utiliza dialplans XML con un esquema compatible con los formatos estándar de dialplan XML de telecomunicaciones, con variables pobladas por el TAS. Esto significa que puedes definir tu propio dialplan según sea necesario, con la lógica comercial para el operador, pero tener todos los datos requeridos como Datos del Repositorio, información de enrutamiento SS7, identidades IMPI / IMPU, normalización del dialplan, etc., etc.

Los dialplans se escriben en priv/templates y toman la forma:

mo_dialplan.xml - Dialplan de Llamadas Originadas desde Móvil
mo_emergency_dialplan.xml - Dialplan de Llamadas de Emergencia Originadas desde Móvil
mt_dialplan.xml - Dialplan de Llamadas Terminadas en Móvil

Puedes ver los Dialplans desde dentro de la Interfaz Web.

Varias variables son establecidas por el TAS antes de que el XML sea analizado, estas variables se imprimen en el registro al inicio de la llamada con sus valores actuales y son muy útiles al definir tu propia lógica de llamadas.

Fundamentos del Dialplan XML de FreeSWITCH

OmniTAS utiliza el mismo sistema de enrutamiento de llamadas XML que el proyecto FreeSWITCH, lo que permite un enrutamiento de llamadas flexible para satisfacer tus necesidades.

Esta sección explica los conceptos básicos y proporciona ejemplos prácticos.

Estructura Básica

Un dialplan consiste en extensiones que contienen condiciones y acciones:

<extension name="description-of-what-this-does">
  <condition field="${variable}" expression="regex-pattern">
    <action application="app_name" data="parameters"/>
    <anti-action application="app_name" data="parameters"/>
  </condition>
</extension>

Las extensiones se evalúan en orden de arriba hacia abajo. Cuando una condición coincide, sus acciones se ejecutan.

Condiciones y Coincidencia de Regex

Las condiciones prueban variables contra expresiones regulares. Si la regex coincide, se ejecutan las acciones; si no, se ejecutan las anti-acciones.

Coincidencia exacta básica:

<condition field="${tas_destination_number}" expression="2222">
  <action application="log" data="INFO Llamando al número de acceso de buzón de voz"/>
</condition>

Coincidencia de múltiples números:

<condition field="${tas_destination_number}" expression="^(2222|3444|3445)$">
  <action application="log" data="INFO Llamando a servicio especial"/>
</condition>

Coincidencia de patrones con grupos de captura:

<condition field="${tas_destination_number}" expression="^1(8[0-9]{9})$">
  <!-- Coincide con 1 seguido de 8 y 9 dígitos más -->
  <action application="log" data="INFO Coincidencia de número gratuito: $1"/>
  <action application="bridge" data="sofia/gateway/trunk/${tas_destination_number}"/>
</condition>

Coincidencia de prefijos:

<condition field="${tas_destination_number}" expression="^00">
  <!-- Coincide con cualquier número que comience con 00 (internacional) -->
  <action application="log" data="INFO Llamada internacional detectada"/>
</condition>

Coincidencia de rangos:

<condition field="${msisdn}" expression="^5551241[0-9]{4}$">
  <!-- Coincide con 55512410000 a 55512419999 -->
  <action application="log" data="INFO Suscriptor en rango"/>
</condition>

Acciones vs Anti-Acciones

Las acciones se ejecutan cuando una condición coincide. Las anti-acciones se ejecutan cuando una condición NO coincide.

<condition field="${cli_withheld}" expression="true">
  <!-- Se ejecuta si el CLI está oculto -->
  <action application="set" data="effective_caller_id_number=anonymous"/>
  <action application="set" data="origination_privacy=hide_number"/>

  <!-- Se ejecuta si el CLI NO está oculto -->
  <anti-action application="log" data="DEBUG CLI es normal"/>
  <anti-action application="set" data="effective_caller_id_number=${msisdn}"/>
</condition>

El atributo continue="true"

Por defecto, cuando coincide la condición de una extensión, el dialplan deja de procesar extensiones adicionales. El atributo continue="true" permite que el procesamiento continúe a la siguiente extensión.

Sin continue (comportamiento predeterminado):

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

<extension name="Never-Reached">
  <!-- Esto NUNCA se ejecuta porque la extensión anterior coincidió -->
  <condition field="${tas_destination_number}" expression="^(.*)$">
    <action application="log" data="INFO Esto no se imprimirá"/>
  </condition>
</extension>

Con 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 extensión aún se evalúa -->
  <condition field="${tas_destination_number}" expression="^(.*)$">
    <action application="bridge" data="sofia/gateway/trunk/${tas_destination_number}"/>
  </condition>
</extension>

Usa continue="true" para:

Extensiones de registro/debugging
Establecer variables que se aplican a múltiples escenarios
Comprobaciones de validación que no enrutaron la llamada

Aplicaciones Comunes

control de llamadas

answer - Responder la llamada (enviar 200 OK)

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

hangup - Terminar la llamada con una causa específica

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

bridge - Conectar la llamada a otro destino

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

<!-- Puente a extensión interna con preferencias de códec -->
<action application="bridge" data="{absolute_codec_string=AMR-WB,AMR,PCMA}sofia/internal/sip:user@domain.com"/>

<!-- Puente con tiempo de espera -->
<action application="bridge" data="{originate_timeout=30}sofia/gateway/trunk/${tas_destination_number}"/>

Variables y Datos de Canal

set - Establecer una variable 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 - Eliminar una variable de canal

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

export - Establecer variable y exportar a B-leg (llamada puenteada)

<action application="export" data="sip_h_X-Account-Code=ABC123"/>

Medios y Prompts

playback - Reproducir un archivo de audio

<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 durante milisegundos especificados

<action application="sleep" data="1000"/>  <!-- Dormir durante 1 segundo -->

echo - Devolver audio al llamante (pruebas)

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

conference - Colocar la llamada en conferencia

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

buzón de voz

voicemail - Acceder al sistema de buzón de voz

<!-- Dejar un mensaje de voz para el buzón -->
<action application="voicemail" data="default default ${msisdn}"/>

<!-- Comprobar el buzón de voz con autenticación -->
<action application="voicemail" data="check auth default default ${msisdn}"/>

Registro y Depuración

log - Escribir en el archivo de registro

<action application="log" data="INFO Procesando llamada desde ${msisdn}"/>
<action application="log" data="DEBUG Destino: ${tas_destination_number}"/>
<action application="log" data="ERROR La llamada falló con causa: ${hangup_cause}"/>

info - Volcar todas las variables de canal al registro

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

Aplicaciones Misceláneas

say - Lectura de números mediante texto a voz

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

send_dtmf - Enviar tonos DTMF

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

Ejemplos Prácticos

Enrutamiento de Servicios de Emergencia:

<extension name="Emergency-911">
  <condition field="${tas_destination_number}" expression="^(911|112)$">
    <action application="log" data="ALERT Llamada de emergencia desde ${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>

Enrutamiento Condicional Basado en 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>

Enrutamiento On-Net vs Off-Net:

<extension name="Route-Decision">
  <condition field="${on_net_status}" expression="true">
    <!-- On-net: enrutamiento de regreso a través de TAS -->
    <action application="log" data="INFO Enrutando a suscriptor on-net"/>
    <action application="bridge" data="sofia/internal/+${tas_destination_number}@10.179.3.60"/>
    <anti-action application="log" data="INFO Enrutando off-net"/>
    <anti-action application="bridge" data="sofia/gateway/trunk/+${tas_destination_number}"/>
  </condition>
</extension>

Manejo de ID de Llamante 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>

Buzón de Voz en Caso de No Respuesta:

<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"/>

    <!-- Si el puente falla, ir al buzón de voz -->
    <action application="log" data="INFO El puente falló, enrutando al buzón de voz"/>
    <action application="answer" data=""/>
    <action application="voicemail" data="default default ${tas_destination_number}"/>
  </condition>
</extension>

Enrutamiento de Rango de Números:

<extension name="Local-Numbers">
  <condition field="${tas_destination_number}" expression="^([2-9]\d{2})$">
    <!-- Extensiones locales de 3 dígitos 200-999 -->
    <action application="log" data="INFO Extensión 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óviles nacionales -->
    <action application="log" data="INFO Llamada móvil 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+$">
    <!-- Llamadas internacionales que comienzan con 00 -->
    <action application="log" data="INFO Llamada internacional"/>
    <action application="bridge" data="sofia/gateway/intl_trunk/${tas_destination_number}"/>
  </condition>
</extension>

Documentación Adicional

Para detalles completos sobre cada aplicación:

Documentación del Dialplan de FreeSWITCH: https://freeswitch.org/confluence/display/FREESWITCH/Dialplan
FreeSWITCH mod_dptools: https://freeswitch.org/confluence/display/FREESWITCH/mod_dptools (referencia completa de aplicaciones)
Referencia de Expresiones Regulares: https://freeswitch.org/confluence/display/FREESWITCH/Regular+Expression
Variables de Canal: https://freeswitch.org/confluence/display/FREESWITCH/Channel+Variables

La wiki de FreeSWITCH contiene documentación detallada para cada aplicación de dialplan, incluidos todos los parámetros y casos de uso.

Variables del Dialplan

Variables establecidas por el TAS en la lógica del dialplan XML:

Variables Comunes (Todos los Tipos de Llamadas)

Configuración Inicial:

destination_number - número de destino traducido
tas_destination_number - número de destino traducido
effective_caller_id_number - número de origen traducido

Llamadas de Emergencia

hangup_case - "none"
ims_private_identity - identidad de usuario privada
ims_public_identity - identidad de usuario pública
msisdn - número de suscriptor (sin +)
imsi - IMSI de la identidad privada
ims_domain - dominio de la identidad privada

Llamadas MT (Terminadas en Móvil)

ims_private_identity - identidad de usuario privada
ims_public_identity - identidad de usuario pública
msisdn - número de suscriptor (sin +)
imsi - IMSI de la identidad privada
ims_domain - dominio de la identidad privada
call_forward_all_destination - destino CFA o "none"
call_forward_not_reachable_destination - destino CFNRc
scscf_address - dirección S-CSCF o "none"
scscf_domain - dominio S-CSCF o "none"
no_reply_timer - tiempo de espera para no respuesta
hangup_case - "none" o "UNALLOCATED_NUMBER"
msrn - MSRN de PRN (si está en roaming) o número desviado de SRI (si el desvío de llamadas está activo)
tas_destination_number - Sobrescritura de destino de enrutamiento (establecido en MSRN o número desviado)

Llamadas MO (Originadas desde Móvil)

hangup_case - "none", "OUTGOING_CALL_BARRED" o "UNALLOCATED_NUMBER"
ims_private_identity - identidad de usuario privada
ims_public_identity - identidad de usuario pública
msisdn - número de suscriptor (sin +)
imsi - IMSI de la identidad privada
ims_domain - dominio de la identidad privada
allocated_time - tiempo asignado por OCS (si la carga en línea está habilitada)
cli_withheld - cadena "true" o "false"
on_net_status - cadena "true" o "false" (si el destino está en la red)
msrn - MSRN para suscriptores en roaming (si corresponde)
tas_destination_number - Sobrescritura de MSRN (si está en roaming)

Llamadas de Emergencia

Las llamadas de emergencia se controlan a través del parámetro de configuración emergency_call_codes y se detectan automáticamente durante la autorización de llamadas.

Configuración

Configura los códigos de llamada de emergencia en tu archivo config/runtime.exs:

config :tas,
  emergency_call_codes: ["911", "912", "913", "sos"],
  # ... otra configuración

Detalles de Configuración:

emergency_call_codes (requerido): Lista de cadenas que representan números de servicio de emergencia
Estos códigos se verifican además de los URN de emergencia SIP (por ejemplo, <urn:service:sos>)
El sistema realiza una comparación de coincidencia exacta contra el número de destino
Códigos comunes incluyen: "911" (EE. UU.), "112" (UE), "000" (AU), "999" (UK), "sos"

Cómo Funciona la Detección de Emergencias

La función Tas.Dialplan.Authorization.is_emergency_call?/2 verifica dos condiciones:

SIP URI Emergency Service URN: Detecta <urn:service:sos> o cualquier URI que contenga "service:sos"
Coincidencia de Número de Destino: Compara Caller-Destination-Number contra los emergency_call_codes configurados

Si cualquiera de las condiciones es verdadera, la llamada se clasifica como de emergencia.

Referencia de Código: Ver lib/dialplan/authorization.ex

Flujo de Procesamiento

Detalles del Flujo de Llamadas:

La llamada llega al TAS
El módulo de autorización verifica el destino contra los patrones de emergencia
Si se detecta una emergencia:
- El tipo de llamada se establece en :emergency
- Se utiliza la plantilla mo_emergency_dialplan.xml
- La autorización OCS se omite normalmente
- La llamada se enruta al gateway PSAP
Se registran métricas con la etiqueta call_type: emergency

Enrutamiento del Dialplan

Define el enrutamiento para llamadas de emergencia en priv/templates/mo_emergency_dialplan.xml. Esta plantilla determina cómo se enrutan las llamadas a tu PSAP (Punto de Respuesta de Seguridad Pública) gateway o URI SIP según los requisitos de tu mercado.

Ejemplo de dialplan de emergencia:

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

Mejores Prácticas

Siempre incluye "sos" en tu lista de códigos de emergencia para compatibilidad con SIP URN
Incluye todos los números de emergencia locales para tu jurisdicción (por ejemplo, 911, 112, 000, 999)
Prueba el enrutamiento de emergencia regularmente usando el Simulador de Llamadas
Omitir OCS para llamadas de emergencia para asegurar que siempre se conecten (configurado a través de skipped_regex)
Configura el gateway PSAP con alta disponibilidad y redundancia
Monitorea las métricas de llamadas de emergencia para asegurar la fiabilidad del sistema

Llamada Originada en Móvil a un Suscriptor Terminando en Móvil en la Misma Red

Puedes enrutar desde tu dialplan a tu dialplan a través de algo como esto:

<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" />

Donde 10.179.3.60 es la IP del TAS (está enroutando la llamada de regreso al TAS) - Solo asegúrate de que la IP del TAS esté en tu lista de allowed_sbc_source_ips.

Documentación Relacionada​

Documentación Principal​

Flujo de Procesamiento de Llamadas​

Implementación de Servicios​

Monitoreo​

Configuración del Dialplan / Enrutamiento de Llamadas​

Fundamentos del Dialplan XML de FreeSWITCH​

Estructura Básica​

Condiciones y Coincidencia de Regex​

Acciones vs Anti-Acciones​

El atributo continue="true"​

Aplicaciones Comunes​

control de llamadas​

Variables y Datos de Canal​

Medios y Prompts​

buzón de voz​

Registro y Depuración​

Aplicaciones Misceláneas​

Ejemplos Prácticos​

Documentación Adicional​

Variables del Dialplan​

Variables Comunes (Todos los Tipos de Llamadas)​

Llamadas de Emergencia​

Llamadas MT (Terminadas en Móvil)​

Llamadas MO (Originadas desde Móvil)​

Llamadas de Emergencia​

Configuración​

Cómo Funciona la Detección de Emergencias​

Flujo de Procesamiento​

Enrutamiento del Dialplan​

Mejores Prácticas​

Llamada Originada en Móvil a un Suscriptor Terminando en Móvil en la Misma Red​

Documentación Relacionada

Documentación Principal

Flujo de Procesamiento de Llamadas

Implementación de Servicios

Monitoreo

Configuración del Dialplan / Enrutamiento de Llamadas

Fundamentos del Dialplan XML de FreeSWITCH

Estructura Básica

Condiciones y Coincidencia de Regex

Acciones vs Anti-Acciones

El atributo continue="true"

Aplicaciones Comunes

control de llamadas

Variables y Datos de Canal

Medios y Prompts

buzón de voz

Registro y Depuración

Aplicaciones Misceláneas

Ejemplos Prácticos

Documentación Adicional

Variables del Dialplan

Variables Comunes (Todos los Tipos de Llamadas)

Llamadas de Emergencia

Llamadas MT (Terminadas en Móvil)

Llamadas MO (Originadas desde Móvil)

Llamadas de Emergencia

Configuración

Cómo Funciona la Detección de Emergencias

Flujo de Procesamiento

Enrutamiento del Dialplan

Mejores Prácticas

Llamada Originada en Móvil a un Suscriptor Terminando en Móvil en la Misma Red