VoxyWatch Integration Guide

VoxyWatch is a self-hosted voice network observability and intelligent diagnostics platform for telecom engineers and NOC teams. It passively receives signaling and media telemetry, correlating root causes with zero cloud dependencies.

Release notes, signed binaries, and source guides on GitHub: github.com/VoxyWatch/publish

Quick install

A single command installs the entire system, auto-detecting your Linux distribution (Debian, Ubuntu, Amazon Linux 2023, RHEL/Rocky):

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

After installation, open https://YOUR-IP. Default credentials: admin / voxywatch (change on first login). Free tier supports up to 100 concurrent calls and unlimited CDRs.

License activation

Get your Hardware ID using node /opt/voxywatch/get-hwid.js or in Settings → License. You can activate via portal or terminal:

1. Via Web Portal: Upload your .key file under Settings → License.

2. Via Terminal: Copy your .key file to /etc/voxywatch/license.key with 0640 permissions.

# 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

SBC Ingestion & Network Architecture

VoxyWatch is 100% vendor-agnostic and compatible with all SBCs, PBXs, and gateways (Cisco, AudioCodes, Ribbon, Kamailio, Asterisk, Metaswitch, etc.).

3 Universal Ingestion Methods

Select the capture method that best fits your voice network topology:

• 1. HEP (v1 / v2 / v3): Standard encapsulation protocol for SIP signaling and RTCP telemetry over UDP/TCP on port 9060.
• 2. SIPREC (Native SRS): Session Recording Server (RFC 7865/7866) receiving recorded streams over UDP or TLS with stereo reconstruction.
• 3. Port Mirroring / Traffic Mirroring (SPAN, ERSPAN, Cloud Mirroring): Passive packet copy from network switches or cloud (Cisco SPAN/RSPAN/ERSPAN, Juniper/MikroTik/Arista Port Mirroring, AWS VPC Traffic Mirroring [VXLAN], GCP Packet Mirroring, VMware vSwitch) via voxywatch-probe, with zero configuration changes to your SBC.

voxywatch-probe — Lightweight capture agent

A standalone capture agent (Go + libpcap) that sniffs SIP/RTP/RTCP from dedicated interfaces or mirrored switch ports, forwarding HEPv3 to VoxyWatch.

Install on PBX/SBC host or dedicated capture node (passive, read-only):

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

Runs as a lightweight systemd service. Verify status with systemctl status voxywatch-probe.

Model-specific guides and SBC configuration matrix: github.com/VoxyWatch/voxywatch-probe/docs/sbc.

SNMP agent & traps

Built-in SNMP v2c/v3 agent and edge-triggered traps for integration with PRTG, Zabbix, Nagios, and enterprise NMS.

Exposed metrics: 30+ OIDs covering system health (CPU, RAM, disk), capture status, and VoIP KPIs (ASR, NER, MOS, jitter, packet loss).

Trap alerts: Edge-triggered on state transitions for capture down, low ASR/MOS, and resource exhaustion.

Download MIB and configure community strings in Settings → SNMP. Default ports: UDP 161 (agent) / UDP 162 (traps).

Incidents & NOC Diagnostics

Every anomaly (trunk degradation, capture loss, sniffer outage, traffic drops) automatically opens an incident with full telemetry timeline and stability-based auto-closure.

Automated telemetry investigation

VoxyWatch samples failing calls, identifies dominant SIP response codes, isolates affected IP routes, and correlates multi-trunk behavior to deliver verifiable root-cause diagnostics.

Statistical confidence

Critical severity requires sustained baseline deviation and minimum call volume (−92% false alerts in production).

Telegram & SMTP Email Alerts

Critical incidents arrive instantly on your phone or NOC inbox with root-cause diagnostics and inline action buttons (Ack · Investigate).

2-Minute Guided Setup

1. Create a Telegram bot via the guided wizard in Settings → Notifications.
2. Each NOC engineer links their chat with a single-use code.
3. Select severity threshold per user or group channel.

Every action is audited under the operator’s portal account and gated by role.

SMTP Email Channel

Built-in SMTP engine to send incident alerts directly to your NOC distribution list or paging system.

Model Context Protocol (MCP Gateway)

VoxyWatch embeds a native MCP server, enabling AI assistants (Claude Desktop, Cursor, local agents) to query real-time voice telemetry without shell or database access.

Enterprise Guardrails & Security

• 12 Read-Only NOC Tools: Query live traffic volume, trunk MOS health, incidents, CDRs, baseline anomalies, and fraud evidence.
• Zero Shell or SQL Access: Strictly sandboxed API. Cannot execute commands, touch raw PCAPs, or modify SBC configurations.
• Scoped Authentication: Protected by dedicated MCP API keys with local audit logging and rate limiting.

Configuration & Setup Guide: MCP Server Documentation on GitHub ↗

Flash Call & Anti-Fraud Intelligence

Passive surveillance to identify automated flash calls and fraudulent international traffic mix shifts without touching live call routing.

Flash Call Detector

Identifies zero-duration automated authentication calls (A2P flash calls / missed-call OTPs) via Port Mirror, HEP, or SIPREC in Shadow or Alerting mode.

Anti-Fraud Intelligence

Early warning for high-risk international destinations, short-call storms, and sudden trunk velocity changes with per-trunk evidence.

Technical specification: FLASH_CALL_DETECTION.md on GitHub ↗

PCI-DSS Source Audio Suppression

RTP audio during payment card entry is discarded directly at the capture source by voxywatch-probe, keeping card data completely out of your network and storage.

How it works

The probe hot-reloads suppression rules dynamically without service restarts, eliminating PCI scope expansion.

Contact Center Workflow

When an agent pauses recording in the CRM, the probe immediately drops the audio stream until resumed.

Technical specification: voxywatch-probe PCI-DSS Specification on GitHub ↗ for JSON schemas and parameters.

Call Audio Transcription

Generate searchable, synchronized text transcripts directly from captured call audio.

Key capabilities

• On-demand per-call transcription directly from the call details view.
• Stereo channel separation: caller and callee transcribed independently and synchronized by timestamp.
• Interactive audio player: clickable text segments jump to exact timestamps.
• Multi-format export: download transcripts in TXT, JSON, and SRT subtitle formats.
• Text search across individual transcripts and the local call catalog.

Privacy & Security

Processed securely on your own infrastructure with 0600 file permissions, memory isolation, and full compliance with PCI-DSS audio suppression.

Technical documentation: SPEECH_TO_TEXT_BETA.md on GitHub ↗

Server Sizing Calculator

Estimate hardware resources based on concurrent call volume, audio retention, and CDR history.

NOC AI Copilot

Diagnostic assistant that analyzes trunk KPIs, baseline anomalies, and telemetry to explain root causes in plain language. Strictly read-only.

Bring Your Own Key (BYOK) — Configured in Settings → AI:

Supports OpenAI, Anthropic Claude, Google Gemini, and local open-source models via Ollama.

Queries are cached locally for efficiency. The copilot is disabled by default until you provide your key.

Integration API /api/v1

Versioned, read-only REST API for billing, ticketing, and external monitoring systems.

Available endpoints: CDR search, SIP JSON traces, PCAP exports, and audio stream downloads.

Authentication & Security: Hashed API keys with granular scopes (cdr:read, trace:read, audio:read), IP whitelisting, and RFC 9457 error responses.

Manage API keys in Settings → API Keys. Example:

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

Billing, Payments & Cancellation

Payments, subscriptions, receipts, and license renewals are securely processed through Stripe.

Manage subscriptions, update payment methods, or download VAT invoices via the Stripe Customer Portal:

Open Stripe Portal

Log in with your purchase email address and one-time verification code.

Subscription Cancellation

You can cancel recurring subscriptions anytime. Access remains active through the end of the paid period.

Refund Terms

Full refunds are available within 14 days of initial purchase if VoxyWatch cannot be deployed in your network environment.