Live Calls

The Live Calls module provides real-time monitoring of active call sessions, plus live call coaching (spy, whisper, barge) for Owners and Supervisors.

Purpose

Use this module to:

• View active calls across your organization
• See call status, caller ID, destination, and duration
• Disconnect individual calls or all active calls
• Coach live calls — spy (listen), whisper (talk to one party), or barge (join)
• Merge WebSocket updates with HTTP polling

Data Sources

Live call data comes from Cloudonix session-update webhooks stored in the session_updates table. The frontend merges:

• HTTP polling: Provides the initial state and full refresh
• WebSocket (Soketi): Provides incremental live updates

Displayed Information

Field	Description
Caller ID	Originating phone number
Destination	Number being called
Direction	Inbound or outbound
Status	Current call state
Duration	How long the call has been active
Session ID	Cloudonix session identifier

Call Statuses

Status	Description
Initiated	Call setup in progress
Ringing	Destination is ringing
Answered	Call is connected
Completed	Call has ended
Failed	Call could not connect

Permissions

Action	Owner	PBX Admin	Supervisor	PBX User	Reporter
View live calls	Yes	Yes	Assigned only	No	No
Disconnect a single call	Yes	Yes	Yes (assigned)	No	No
Disconnect All / Clear Stale	Yes	Yes	No	No	No
Coach calls (spy/whisper/barge)	Yes	No	Yes (assigned)	No	No

The per-row Actions column (Spy, Whisper, Barge, Disconnect) is visible only to Owner and Supervisor. Supervisors see and act on only the calls within their assigned scope.

UI Workflow

Monitor Active Calls

1. Navigate to Live Calls in the sidebar
2. Use the polling interval selector to choose refresh frequency (manual, 1s, 5s, 15s, 30s, 60s)
3. View the active call cards

Disconnect a Single Call

1. Find the call card
2. Click Disconnect
3. Confirm the action

The call is marked as recentlyDisconnected for 10 seconds so it does not reappear while Cloudonix processes the disconnect.

Disconnect All Calls

1. Click Disconnect All
2. Confirm the action in the danger dialog
3. The system disconnects calls sequentially with a 200 ms delay

warning

Disconnecting calls is immediate and cannot be undone. Use this power responsibly.

Call Coaching (Spy / Whisper / Barge)

Owners and Supervisors can coach a live call directly from the Actions column, using the Web Phone. Three modes are available:

Mode	Icon	What it does
Spy	Listen	Silently monitor the call; neither party hears you
Whisper	Talk	Speak to one party (caller or callee) without the other hearing
Barge	Join	Join the call so all parties hear you

How to Coach a Call

1. Ensure your Web Phone is available (Owner/Supervisor with an extension).
2. On a live call row, click Spy or Barge, or choose a party from the Whisper dropdown (Caller or Callee).
3. The Web Phone automatically opens and dials the coaching target, showing a short label (Spy, Whisper, or Barge).
4. Press # on the keypad, or end the call, to stop coaching. The Web Phone then closes.

Security

Coaching is protected by two independent authorization layers:

• UI layer — The coach-target endpoint enforces role (owner/supervisor), supervisor scope, tenant isolation, and that the call is active. It only ever hands out the target's secret session token per request; the token is never in the bulk active-calls list.
• Telephony layer — When the coaching target is dialed, the /voice/route webhook re-authorizes the request before emitting the Cloudonix <Coach> verb. This is the real gate: a guessed or replayed target is re-checked at call time.

Supervisor scope

Supervisors can only coach calls that fall within their assigned users and ring groups. Attempting to coach an out-of-scope call returns 403.

Key Data Fields

session_updates Table

Column	Type	Notes
id	bigint	Primary key
organization_id	FK	Tenant scope
session_id	integer	Cloudonix session ID
session_token	string	Used for Cloudonix API disconnect
event_id	string	Idempotency key
domain_id	integer
domain	string
caller_id	string
destination	string
direction	string
status	string
session_created_at	datetime
session_modified_at	datetime
start_time	datetime nullable
answer_time	datetime nullable
call_ids	array
profile	array	Includes QoS and AMD data

Related API Endpoints

Method	Endpoint	Purpose
GET	/v1/session-updates/active	List active calls (add ?supervisor=true to scope)
GET	/v1/session-updates/active/stats	Active call statistics
GET	/v1/session-updates/{sessionId}	Session details
DELETE	/v1/session-updates/{sessionId}/disconnect	Disconnect a call
POST	/v1/session-updates/{sessionId}/coach-target	Resolve a spy/whisper/barge dial target

See the OPBX REST API reference for full schemas.

Related Modules

• Supervisors — Scope which calls a supervisor can view and coach
• Web Phone — In-browser softphone used to place and coach calls
• Call Logs — Historical CDR view
• Call Notifications — Webhook events for call status changes