Real-Time Supervisor View API

The Real-Time Supervisor View APIs provide programmatic access to live agent states and queue health across voice and digital channels, enabling developers to build custom wallboards, automated SLA alerts, and staffing integrations that surface real-time operational data to supervisors.

Strategic Overview

These endpoints are the data foundation for live wallboards and supervisor monitoring dashboards. Unlike historical reporting APIs which aggregate completed interactions, these endpoints return point-in-time snapshots of what is happening right now across agents and queues.

Key Use Cases

• Live Wallboard Displays: Surface agent states, queue depths, and staffing levels on a real-time operations display visible to the floor.
• Supervisor Intervention: Identify agents stuck in pending disposition, queues with zero available agents, or calls exceeding SLA thresholds before they escalate.
• Staffing Validation: Cross-reference staffed vs. available counts against scheduled headcount to detect phantom logins or agents who have broken state.

Real-Time vs. Latency Expectations

• Data Availability: Snapshot data is updated continuously. The lastUpdate field on each record reflects the timestamp of the most recent state change for that entity.
• Counter Reset: Daily counters (abandons, SLA pass/fail, etc.) reset at midnight in the account's configured timezone — not UTC. Agent session counters reset on logout.

Required Permissions & Scopes

1. Configure OAuth Scopes

To authenticate, your application must be configured with the following permission in the Developer Portal:

• ReadAccounts: Required to validate account context and access real-time platform data.

2. Enable Platform Permissions

The authenticating user must have reporting access enabled in the RingCX Admin portal:

1. Log in to RingCX Admin.
2. Navigate to Users > Administrators.
3. Select the target user and ensure the appropriate reporting rights are enabled.

{
    "errorCode": "access.denied.exception",
    "generalMessage": "You do not have permission to access this resource",
    "timestamp": 1611847650696
}

Agent States

Returns a live snapshot of every agent currently logged in to the account — their current state, active call details, and session-level performance counters.

GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{subaccountId}/realTimeData/agent

Request Parameters

Response Details

Returns an array of AgentStats objects — one per logged-in agent session. Key fields include the agent's current agentState (e.g., AVAILABLE, ON_CALL, AWAY, WRAP_UP), stateTime in seconds, live call identifiers (callUii, callAni, callDnis), and session counters (callsHandled, totalTalkTime) that reset on logout.

Inbound Queue Health (ACD)

Returns real-time statistics for every inbound voice queue in the account, including live activity, staffing levels, and daily performance counters.

GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{subaccountId}/realTimeData/inbound

Request Parameters

Response Details

Returns an array of AcdStats objects — one per inbound queue. Key fields include inQueue (calls waiting), longestInQueue (seconds the oldest waiting call has been holding), staffed and available agent counts, and daily SLA counters (slaPass, slaFail) that reset at midnight.

Chat Queue Health

Returns real-time statistics for every chat queue in the account, mirroring the structure of the inbound voice endpoint for digital channels.

GET https://ringcx.ringcentral.com/voice/api/v1/admin/accounts/{subaccountId}/realTimeData/chat

Request Parameters

Response Details

Returns an array of ChatStats objects — one per chat queue. Key fields mirror the inbound voice schema: inQueue, longestInQueue, staffed, available, and daily counters including totalChatTime which accumulates active session duration.

Implementation Strategy

For most supervisor dashboards, a single polling loop fetches all three endpoints in sequence and updates the display on each cycle.

Recommended Pattern

Poll all three endpoints on a consistent interval and use lastUpdate on each record to detect whether an entity's state has actually changed before triggering a UI update.

Sample Implementation (Python)

import requests
import time

BASE_URL = "https://ringcx.ringcentral.com/voice/api/v1/admin/accounts"
ACCOUNT_ID = "12345"
POLL_INTERVAL_SECONDS = 15

def fetch_supervisor_snapshot(token):
    """Fetches agent states, inbound queue stats, and chat queue stats in one pass."""
    headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json'
    }

    endpoints = {
        'agents':  f"{BASE_URL}/{ACCOUNT_ID}/realTimeData/agent",
        'inbound': f"{BASE_URL}/{ACCOUNT_ID}/realTimeData/inbound",
        'chat':    f"{BASE_URL}/{ACCOUNT_ID}/realTimeData/chat",
    }

    snapshot = {}
    for key, url in endpoints.items():
        response = requests.get(url, headers=headers)
        if response.status_code == 200:
            snapshot[key] = response.json()
        elif response.status_code == 429:
            print(f"Rate limited on {key} — backing off.")
            time.sleep(5)
        else:
            print(f"Error fetching {key}: {response.status_code}")

    return snapshot

def monitor(token):
    while True:
        snapshot = fetch_supervisor_snapshot(token)

        # Example: flag any inbound queue where longest wait exceeds 60 seconds
        for queue in snapshot.get('inbound', []):
            if queue.get('longestInQueue', 0) > 60:
                print(f"ALERT: {queue['gateName']} — longest wait {queue['longestInQueue']}s")

        time.sleep(POLL_INTERVAL_SECONDS)

if __name__ == "__main__":
    monitor("YOUR_ACCESS_TOKEN")

• Last updated:
• Contributors