Guía de integración & Referencia técnica

VoxyWatch es una plataforma de observabilidad de redes de voz y diagnóstico inteligente para ingenieros de telecomunicaciones y operadores de NOC. Monitorea tráfico SIP y calidad RTP con cero dependencias de nube.

Notas de versión, binarios firmados y guías en GitHub: github.com/VoxyWatch/publish

Instalación rápida

Un solo comando instala todo. Detecta automáticamente tu distribución Linux (Debian, Ubuntu, Amazon Linux 2023, RHEL/Rocky) y despliega el motor de telemetría:

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/publish/main/install.sh | sudo bash

Tras la instalación, abre https://TU-IP. Credenciales por defecto: admin / voxywatch (cámbialas en el primer inicio). La versión gratuita incluye hasta 100 llamadas concurrentes y CDRs ilimitados.

Activación de licencia

Obtén tu Hardware ID con node /opt/voxywatch/get-hwid.js o en Ajustes → Licencia. Puedes activar tu licencia de dos formas:

1. Desde el portal web: Sube tu archivo .key en Ajustes → Licencia.

2. Desde la terminal: Copia tu archivo .key en /etc/voxywatch/license.key con permisos 640.

# Terminal activation: Copy your license file into place
cp voxywatch.key /etc/voxywatch/license.key
chown root:voxywatch /etc/voxywatch/license.key
chmod 640 /etc/voxywatch/license.key

Compatibilidad con SBCs y Métodos de Ingesta

VoxyWatch es 100% agnóstico al fabricante y compatible con todos los SBCs, PBXs y gateways del mercado (Cisco, AudioCodes, Ribbon, Kamailio, Asterisk, Metaswitch, etc.).

3 Métodos Universales de Ingesta

Recibe telemetría a través de tres vías universales según tu arquitectura de red:

• 1. HEP (v1 / v2 / v3): Protocolo de encapsulación para señalización SIP y telemetría RTCP por UDP/TCP en puerto 9060.
• 2. SIPREC (SRS Nativo): Servidor de grabación de sesiones (RFC 7865/7866) con reconstrucción de audio estéreo directa.
• 3. Port Mirroring / Traffic Mirroring (SPAN, ERSPAN, Cloud Mirroring): Copia pasiva de paquetes desde el switch de red o nube (Cisco SPAN/RSPAN/ERSPAN, Juniper/MikroTik/Arista Port Mirroring, AWS VPC Traffic Mirroring [VXLAN], GCP Packet Mirroring, VMware vSwitch) mediante voxywatch-probe, sin tocar la configuración del SBC.

voxywatch-probe — agente ligero de captura

Agente de captura (Go + libpcap) para inspeccionar SIP/RTP/RTCP en la tarjeta de red o tráfico espejeado por Port Mirror y reenviarlo como HEP v3 a VoxyWatch.

Instalación en el servidor SBC/PBX o nodo recolector (captura pasiva de solo lectura):

curl -fsSL https://raw.githubusercontent.com/VoxyWatch/voxywatch-probe/master/install.sh | sudo bash -s -- --server YOUR_VOXYWATCH:9060

Se ejecuta como servicio systemd en segundo plano. Verifica su estado con systemctl status voxywatch-probe.

Guías por modelo y matriz de compatibilidad SBC: github.com/VoxyWatch/voxywatch-probe/docs/sbc.

Agente SNMP y traps

Agente SNMP v2c/v3 integrado con traps por flanco para integración con PRTG, Zabbix, Nagios y NMS empresariales.

Métricas expuestas: Más de 30 OIDs con salud del host (CPU, RAM, disco), estado de captura y KPIs de VoIP (ASR, NER, MOS, jitter, pérdida).

Traps: Disparo por cambio de estado ante pérdida de captura, sniffer inactivo o degradación severa de calidad.

Descarga la MIB y configura credenciales en Ajustes → SNMP. Puertos por defecto: UDP 161 (agente) / UDP 162 (traps).

Incidentes y Diagnóstico para NOC

Cada anomalía detectada (degradación de troncal, pérdida de captura, caídas de tráfico) abre un incidente con línea de tiempo auditable y autocierre por estabilidad.

Investigación automática con telemetría

VoxyWatch analiza muestras de llamadas fallidas, códigos de error SIP dominantes y rutas IP afectadas, correlacionando múltiples troncales para identificar la causa raíz en segundos.

Confianza estadística

La severidad crítica requiere muestras mínimas y desviación de baseline confirmada (−92% de alertas falsas en producción).

Alertas en Telegram y Correo SMTP

Las alertas críticas llegan a tu teléfono o bandeja del NOC con diagnóstico adjunto y botones de acción (Reconocer · Investigar) para resolver fallas al instante.

Configuración rápida en 2 minutos

1. Crea tu bot de Telegram guiado desde Ajustes → Notificaciones.
2. Cada operador vincula su chat con un código de un solo uso.
3. Configura el nivel de severidad deseado por usuario o canal grupal.

Cada acción queda auditada con el usuario del portal y restringida por rol.

Canal de Correo SMTP

Integración SMTP global para enviar alertas inmediatas a listas de distribución o sistemas de guardia.

Servidor MCP (Model Context Protocol)

VoxyWatch incorpora un servidor nativo de MCP. Conecta tu IDE local (Cursor, VS Code) o asistentes de IA directamente a la telemetría de tu NOC sin acceso a consola ni base de datos.

Capacidades clave y seguridad

• 12 Herramientas NOC de solo lectura: Acceso en tiempo real a volumen de tráfico, salud MOS de troncales, incidentes activos, búsqueda de CDRs y evidencia de fraude.
• Sin acceso a Shell ni SQL: La pasarela MCP está estrictamente aislada en sandbox. No puede ejecutar comandos ni alterar enrutamientos.
• Autenticación con permisos específicos: Protegido por claves API MCP dedicadas con registro de auditoría local y límites de tasa.

Configuración e integración: Consulta la Guía de Servidor MCP en GitHub ↗

Flash Call & Detección de Fraude

Monitoreo pasivo para detectar llamadas de autenticación flash y patrones de abuso internacional sin intervenir en el tráfico.

Detector de Flash Call

Identifica llamadas de autenticación de cero duración (A2P OTPs y flash calls) mediante observación pasiva por Port Mirror, HEP o SIPREC, en modo Shadow o Alerting.

Inteligencia Antifraude

Alerta temprana sobre nuevos destinos de alto riesgo, ráfagas de llamadas cortas y anomalías en el mix de tráfico internacional por troncal.

Documentación técnica completa: FLASH_CALL_DETECTION.md en GitHub ↗

Supresión de audio para entornos PCI-DSS

El audio RTP durante el ingreso de tarjetas de pago se descarta directamente en la fuente mediante voxywatch-probe, evitando que llegue a tu red o almacenamiento.

Cómo funciona

El Probe recarga dinámicamente las reglas de supresión sin necesidad de reiniciar servicios.

Flujo en Contact Centers

Cuando un agente pausa la grabación en su CRM, el Probe detiene inmediatamente el envío del flujo de audio sensible.

Especificación técnica completa: Especificación PCI-DSS en GitHub ↗ para esquemas JSON y parámetros.

Transcripción de Audio de Llamadas

Generación de transcripciones textuales indexadas y buscables a partir del audio capturado por VoxyWatch.

Capacidades principales

• Generación bajo demanda por llamada desde el detalle de la llamada.
• Separación estéreo: transcripción independiente de originador y destino sincronizados por timestamp.
• Reproductor interactivo: segmentos clicables que navegan la reproducción de audio.
• Exportación en múltiples formatos: descarga en TXT, JSON y subtítulos SRT.
• Búsqueda textual de palabras clave en el catálogo de llamadas transcritas.

Privacidad y Seguridad

Procesamiento seguro en tu propia infraestructura con permisos 0600, límites de memoria y respeto estricto a la supresión PCI-DSS.

Especificación técnica completa: SPEECH_TO_TEXT_BETA.md en GitHub ↗

Calculadora de dimensionamiento de servidor

Estima el hardware requerido según tu volumen de llamadas, si capturas audio y la ventana de retención.

Copiloto IA para NOC

Asistente de diagnóstico que analiza KPIs de troncales, anomalías de baseline y telemetría para explicar la causa raíz en lenguaje claro. Estrictamente de solo lectura.

Trae tu propia clave (BYOK) — Configuración en Ajustes → IA:

Compatible con OpenAI, Anthropic Claude, Google Gemini y modelos locales mediante Ollama.

Tus consultas se gestionan de forma privada con caché local. El copiloto está desactivado por defecto hasta que configures tu clave.

API de integración /api/v1

API REST versionada de solo lectura para sistemas de tarificación y monitoreo externo.

Endpoints disponibles: Búsqueda de CDRs, trazas SIP en JSON, exportación de PCAP y flujos de audio.

Autenticación y seguridad: Claves API con permisos específicos (cdr:read, trace:read, audio:read), listas blancas de IP y errores RFC 9457.

Administra tus claves en Ajustes → Claves API. Ejemplo:

curl -H "Authorization: Bearer YOUR_KEY" \
     https://YOUR-VOXYWATCH/api/v1/cdr?from=2026-06-01&to=2026-06-07&carrier=acme

Facturación, Pagos y Cancelación

Los pagos, suscripciones y licencias se procesan de forma segura a través de Stripe.

Administra tu suscripción o descarga facturas desde el portal seguro de Stripe:

Abrir Portal de Stripe

Ingresa con el correo de compra y el código de verificación que recibirás de Stripe.

Cancelación de suscripción

Puedes cancelar tu suscripción en cualquier momento. El acceso se mantiene hasta el final del periodo pagado.

Términos de reembolso

Reembolso completo disponible dentro de los primeros 14 días si VoxyWatch no puede operar en tu red.