Real-Time Campaign Operations API

The Real-Time Campaign Operations APIs provide programmatic access to live outbound dialing activity and IVR self-service traffic, enabling developers to build custom dashboards, automated alerts, and integrations that surface campaign pacing, dial outcome health, and IVR containment data in real time.

Strategic Overview

These endpoints surface the real-time state of your outbound campaigns and IVR applications. Unlike the historical reporting APIs, which provide post-hoc analysis, these endpoints are designed for programmatic consumption of live operational state — feeding custom wallboards, triggering automated alerts, or correlating RingCX campaign data with external systems like a CRM or workforce management platform.

Key Use Cases

• Campaign Pacing Dashboards: Monitor active calls, agent availability, and lead state counts in real time to identify campaigns that are under- or over-dialing.
• Dial Outcome Monitoring: Track live answer rate, AMD detection, and abandon rate to catch campaign health issues as they develop.
• IVR Containment Tracking: Measure how many callers are completing IVR self-service flows versus transferring to a live agent queue.

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 update for that entity.
• Counter Reset: All daily counters reset at midnight in the account's configured timezone — not UTC.

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
}

Outbound Campaign Stats

Returns real-time dial activity and outcome counters for every outbound campaign in the account.

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

Request Parameters

Response Details

Returns an array of OutboundStats objects — one per campaign. Key fields include active (calls in progress), ready and pending lead counts, staffed and available agent counts, and daily dial outcomes broken out by result type (answer, machine, noanswer, abandon, etc.).

A few particularly useful derived metrics:

• Agent occupancy: If available drops to zero while ready is non-zero, the campaign is agent-starved and leads are backing up.
• Human answer rate: answer ÷ connects gives a live view of the proportion of calls reaching a live person.
• AMD rate: machine ÷ connects shows the proportion of calls landing on voicemail — a sudden spike may indicate list quality issues.

IVR Application Stats

Returns real-time traffic counts for every Visual IVR application in the account, enabling monitoring of self-service load and agent handoff volumes.

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

Request Parameters

Response Details

Returns an array of IvrStats objects — one per IVR application. Key fields include active (callers currently in the IVR), presented (total calls entered today), and transfer destination counters (transferGate, transferCloud, transferTrac) that let you calculate a real-time self-service containment rate:

containment = (presented - transferGate - transferCloud - transferTrac) / presented

Implementation Strategy

For campaign operations dashboards, poll both endpoints on the same cycle to correlate outbound performance with IVR activity.

Recommended Pattern

Poll both endpoints on a consistent interval and use lastUpdate on each record to detect whether data has changed before refreshing display elements.

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_campaign_snapshot(token):
    """Fetches outbound campaign stats and IVR stats in one pass."""
    headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json'
    }

    endpoints = {
        'outbound': f"{BASE_URL}/{ACCOUNT_ID}/realTimeData/outbound",
        'ivr':      f"{BASE_URL}/{ACCOUNT_ID}/realTimeData/ivr",
    }

    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_campaign_snapshot(token)

        # Example: flag agent-starved campaigns
        for campaign in snapshot.get('outbound', []):
            if campaign.get('available', 0) == 0 and campaign.get('ready', 0) > 0:
                print(f"ALERT: {campaign['campaignName']} — agent-starved, {campaign['ready']} leads waiting")

        # Example: log IVR containment rate
        for ivr in snapshot.get('ivr', []):
            presented = ivr.get('presented', 0)
            if presented > 0:
                transfers = ivr.get('transferGate', 0) + ivr.get('transferCloud', 0) + ivr.get('transferTrac', 0)
                containment = round((presented - transfers) / presented * 100, 1)
                print(f"{ivr['visualIvrName']} containment: {containment}%")

        time.sleep(POLL_INTERVAL_SECONDS)

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

• Last updated:
• Contributors