Live OCS Monitor & Real-Time Telephony Supervision Module Documentation

Table of Contents

1. Module Overview (Technical)
2. Module Overview (Commercial & Business Value)
3. 🎯 User Roles & Key Capabilities
4. Visual Interface & Form Structure
5. Architectural Flow & Real-Time OCS Supervision Engine
6. Common Scenarios & Operational Playbooks
7. Troubleshooting & Diagnostic Commands
8. Model Context Protocol (MCP) AI Integration
9. Glossary

---

1. Module Overview (Technical)

The Live OCS Monitor & Real-Time Telephony Supervision module provides live, second-by-second visibility into active SIP dialogs traversing Ring2All SBC and supervised by the Ring2All Billing Online Charging System (OCS).

Subsystems & Real-Time Telemetry

 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Ring2All SBC (Kamailio Core)                      │
 │  • Supervised SIP Dialogs (`dlg` module)                               │
 │  • Media RTP Streams Relay (RTPEngine)                                 │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │ (JSON-RPC / REST Hook)
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │               Ring2All Billing OCS Engine (`/api/ocs`)                 │
 │  • In-Memory Active Registry (`globalActiveCalls`)                     │
 │  • Running Accrued Revenue Ticker (1-second update cycle)              │
 │  • Real-Time Credit Limit & Wallet Balance Guard                       │
 │  • Remote Call Teardown Dispatcher (`dlg.end_dlg`)                     │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │            Web Operations Dashboard (`/live-monitor`)                  │
 │  • Live Call Duration Ticker                                           │
 │  • Active Channels & Real-Time CPS Metrics                             │
 │  • One-Click Administrative Call Disconnection                         │
 └────────────────────────────────────────────────────────────────────────┘

Key Technical Parameters Monitored

• Supervised Active Dialogs: Count of live, bi-directional SIP dialogs currently established across the network.
• Media Channels: Active RTP and WebRTC audio media relay sockets maintained by RTPEngine (2 channels per standard audio call).
• Live Accrued Revenue: Calculated in real time for all in-progress calls using dynamic second-by-second evaluation: $$\text{Accrued Cost} = \text{Connection Fee} + \left(\text{Rate per Minute} \times \frac{\text{Elapsed Seconds}}{60}\right)$$
• Active Calls Per Second (CPS): Rolling throughput calculation representing transaction intensity across telecom nodes.

---

2. Module Overview (Commercial & Business Value)

• Immediate Fraud Mitigation: Enables Network Operations Center (NOC) engineers to detect and instantly terminate toll fraud, PBX compromises, and international revenue share fraud (IRSF) while calls are in progress.
• Zero Prepaid Credit Overrun: The OCS engine monitors wallet balances in real time, automatically dispatching teardown signals to Ring2All SBC before a prepaid customer’s account can enter negative territory.
• Carrier Capacity Supervision: Allows engineering teams to ensure outbound traffic does not breach agreed carrier channel caps, preventing upstream SIP 503 Service Unavailable rejections.
• Executive Revenue Telemetry: Real-time visibility of gross platform monetization as calls occur, without having to wait for offline batch rating processes.

---

3. 🎯 User Roles & Key Capabilities

User Role	Key Permissions	Core Responsibilities & Workflows
Super Administrator	Full Control & Emergency Cutoff	Supervises platform-wide telephony health, forces termination of unauthorized calls, and audits high-exposure accounts.
NOC Engineer / Telecom Supervisor	Live Telemetry & Call Teardown	Monitors concurrent call volumes, tracks RTPEngine media relay performance, and disconnects hung or looped SIP dialogs.
Fraud Analyst	Traffic Anomaly Detection	Identifies suspicious calling patterns (e.g. concurrent calls to premium international destinations), audits caller CLI, and initiates customer freezes.
Billing Operator	Real-Time Spend Verification	Validates that newly configured Rate Cards and tariffs apply the expected per-minute rates on active calls.

---

4. Visual Interface & Form Structure

4.1 Live OCS Monitor (Dashboard View)

The Live Call Monitor & SBC Channels interface combines real-time telephony KPI status cards (Supervised Calls, Media Channels, Calls Per Second, Accrued Revenue, and Core Health) with an interactive table of active calls featuring live updating duration timers and one-click disconnect controls.

4.2 Telemetry KPI Metrics Reference

Metric Card	Unit	Source	Description & Operational Significance
Supervised Calls	Integer	In-Memory OCS Registry	Number of active established SIP dialogs being charged in real time.
Media Channels	Integer	RTPEngine Socket	Active bidirectional audio RTP streams relayed across the perimeter SBC.
Calls Per Second (CPS)	Decimal	Rolling Counter	Real-time call establishment rate across all configured telecom nodes.
Accrued Revenue	Currency ($)	Dynamic Rating Ticker	Total live monetary value accumulated by currently connected calls.
SBC Core Health	Status Badge	Heartbeat Ping	Operational status of the connected Kamailio SIP signaling engine.

4.3 Active Calls Table Fields

Field Name	Format	Description
Call UUID & Status	String / Pulse Badge	Unique SIP call identifier with pulsing activity indicator.
Caller (CLI)	E.164 String	Originating phone number presented by the caller.
Destination	E.164 / Geo Name	Target dialed number and geographical destination name.
Customer & Account	Text	Corporate customer name and account number being debited.
Carrier Provider	Text	Terminating wholesale carrier handling the outbound hop.
Rate / Min	$0.0000	Applicable retail per-minute tariff from the customer’s Rate Card.
Live Duration	MM:SS (Live Ticker)	Exact running call duration updated every 1,000 milliseconds.
Accrued Cost	$0.0000	Real-time calculated charge to date for the active session.
Actions	Disconnect Button	Sends an immediate SIP BYE / dlg.end_dlg command to terminate the call.

---

5. Architectural Flow & Real-Time OCS Supervision Engine

 ┌────────────────────────────────────────────────────────────────────────┐
 │           Inbound Call Arrives at Ring2All SBC Core                    │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │  Step 1: Real-Time Pre-Authorization Check (`/api/ocs/pre-auth`)       │
 │  • Verify Customer status: `active`                                    │
 │  • Check balance: Prepaid (wallet > $0) or Postpaid (within limit)     │
 │  • Resolve retail rate & calculate max allowed duration (seconds)      │
 │  • Return: `{ authorized: true, maxDurationSeconds: 1800 }`            │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
                                     ▼
 ┌────────────────────────────────────────────────────────────────────────┐
 │  Step 2: Live Dialog Registration (`globalActiveCalls`)                │
 │  • SIP 200 OK received: call connected                                │
 │  • Register session in OCS in-memory registry                          │
 │  • Live monitor web dashboard displays running timers                  │
 └───────────────────────────────────┬────────────────────────────────────┘
                                     │
            ┌────────────────────────┴────────────────────────┐
            │                                                 │
            ▼ (Normal Call End)                               ▼ (Administrative Kill / Balance Exhausted)
 ┌───────────────────────────────────────┐         ┌───────────────────────────────────────┐
 │   Call Terminates (SIP BYE)           │         │   Force Teardown Signal               │
 │  • Remove from `globalActiveCalls`    │         │  • Send `dlg.end_dlg` to SBC via RPC  │
 │  • Write final CDR to `cdrs_rated`    │         │  • Drop dialog and release media      │
 └───────────────────────────────────────┘         └───────────────────────────────────────┘

---

6. Common Scenarios & Operational Playbooks

Scenario A: Terminating a Suspected Toll Fraud Call

1. In the Live OCS Monitor, search for high-cost international prefixes (e.g. +232, +882, +370).
2. Identify any suspicious calls where duration or rate per minute is extraordinarily high.
3. Click the red Disconnect (phone off) button on the call row.
4. Confirm the prompt: “Disconnect live call dialog?”.
5. The platform sends a direct dlg.end_dlg RPC command to Ring2All SBC Core, immediately terminating the call and releasing all media sockets.

Scenario B: Monitoring Live Capacity During Peak Calling Windows

1. Verify that Live Stream: ON is illuminated green in the top toolbar (refreshes every 2.5 seconds).
2. Monitor the Media Channels metric to verify that Perimeter RTPEngine capacity remains within healthy operating thresholds.
3. Check the SBC Core Health and Media Relay indicators to ensure zero packet drop or signaling latency.

---

7. Troubleshooting & Diagnostic Commands

Query Live Dialogs Directly on Kamailio SBC Core

kamcmd dlg.list

Inspect Active In-Memory Calls via Billing API

curl -s -H "Authorization: Bearer <TOKEN>" https://192.168.10.29/api/ocs/live-calls | jq .

Force Disconnect a Call via Command Line

curl -s -X POST https://192.168.10.29/api/ocs/kill-call \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"callUuid": "call-7b91a2-live-01"}'

---

8. Model Context Protocol (MCP) AI Integration

The Live OCS Monitor & Real-Time Telephony Supervision module connects directly to the Ring2All BSS MCP Server, empowering NOC operators and telephony AI agents to inspect live traffic, monitor real-time CPS, and execute emergency call hangups.

Available MCP Tools

Tool Name	Access Role	Description & Primary Function	Example Arguments
get_live_calls_telemetry	Telecom & Carrier Engineer / Admin	Retrieves real-time active call telemetry, CPS metrics, active channels, and supervised sessions from OCS engine.	{}
disconnect_live_call_ocs	Super Administrator	Forcefully terminates an active call session in the Online Charging System (OCS) and signals the telecom switch.	{"callId": "call-7b91a2-live-01"}

Sample MCP Tool Execution: get_live_calls_telemetry

Request Payload

{
  "name": "get_live_calls_telemetry",
  "arguments": {}
}

Response Payload

{
  "activeCallsCount": 14,
  "callsPerSecond": 3.8,
  "activeChannels": 28,
  "estimatedHourlyRevenue": 42.60,
  "calls": [
    {
      "callId": "call-7b91a2-live-01",
      "caller": "+13055550199",
      "callee": "+442079460991",
      "durationSeconds": 85,
      "currentCost": 0.0170,
      "customerName": "Cuadra Telecom Corp",
      "carrier": "Telnyx Primary Carrier"
    }
  ]
}

Conversational AI Prompts for Copilot

• “What is our current active call count and calls-per-second rate?”
• “List all active calls that have exceeded 60 minutes in duration.”
• “Disconnect active call session call-7b91a2-live-01 immediately.”

---

9. Glossary

• Active Channels: The count of concurrent audio and media relay channels active on the platform.
• Calls Per Second (CPS): Measure of telephony signaling throughput representing newly initiated calls per second.
• OCS (Online Charging System): Telecom architecture component that inspects customer balances in real time before and during calls.
• Pre-Authorization: Real-time query performed by the SBC to the OCS before completing an outbound call to verify credit.
• SIP Dialog: A peer-to-peer SIP relationship between two user agents that persists for a measurable duration.
• Model Context Protocol (MCP): Open protocol standard that enables secure, controlled integration between Large Language Models and external tools, databases, and telecom rating engines.