Ringba Agent Availability API Documentation

This document describes the production agent-availability integration used by Ringba to determine whether APFSC can receive inbound calls in the primary call center ingroups.

1. Overview

The Ringba availability check is a simple, read-only HTTP API that aggregates real-time queue statistics from the VICIdial in_group_status Non-Agent API and exposes a minimal JSON contract for Ringba to decide whether to send a call to APFSC.

• Purpose: Indicate, in real time, whether at least one eligible agent is waiting to receive inbound calls.
• Backend: VICIdial ingroup status (function=in_group_status).
• Consumers: Ringba ping/pong routing, and APFSC internal monitoring.

2. Endpoint

HTTP Method: GET
URL: https://arden.apfsc.org/ringba/agent-availability
Protocol: HTTPS only
Authentication: Shared secret header
Idempotence: Safe & read-only

Required Headers

Header	Required	Description
X-Ringba-Ping-Secret	Yes	Shared secret provisioned out-of-band by APFSC. Used to authenticate Ringba ping requests. The value is not returned in any response or documentation.

No query-string parameters or request body are required or supported.

Sample Request

curl -X GET 
  https://arden.apfsc.org/ringba/agent-availability 
  -H 'X-Ringba-Ping-Secret: <shared-secret>'

3. Response Contract

Success

Status: HTTP 200 OK
Content-Type: application/json; charset=utf-8

On success, the response body is a single JSON object:

Field	Type	Description
available	boolean	true if at least one eligible agent is currently waiting; otherwise false.
ready	integer	Sum of agents_waiting across the configured ingroups.
logged_in	integer	Sum of agents_logged_in across the configured ingroups.
checked_at	string (ISO 8601 UTC)	Timestamp in UTC when VICIdial was queried.

Sample 200 Response

{
  "available": true,
  "ready": 3,
  "logged_in": 7,
  "checked_at": "2026-08-26T16:52:03Z"
}

4. Ingroup Scope & Availability Semantics

The API derives availability from VICIdial’s Non-Agent API using function=in_group_status with CSV output enabled. Only aggregate queue metrics are used; no per-agent identifiers are exposed.

Backend Source

• API: VICIdial Non-Agent API, function=in_group_status
• Format: CSV with headers (stage=csv, header=YES)
• Fields: group_id, agents_waiting, agents_logged_in

Ingroup Scope

• MarketCall
• PX
• Combined rows such as MarketCall PX or MarketCall|PX for joint statistics.

Availability Rule

• ready = sum of agents_waiting across configured ingroups.
• logged_in = sum of agents_logged_in.
• available = true if ready > 0; otherwise false.

5. Ringba Integration Example

Key rule: treat the endpoint as available only when status is HTTP 200 and the JSON body contains "available": true.

Conceptual Ping Logic

// Pseudocode for Ringba
if (statusCode === 200 &&
    bodyContains('"available": true')) {
  // Send call to APFSC
} else {
  // Treat as unavailable and route to next destination
}

6. Failure & Error Behavior

The integration is intentionally fail-closed. If anything prevents a confident "available": true response, the API returns available: false or a non-2xx HTTP status, and Ringba should not send calls to APFSC for that check.

Authentication Errors

Status: HTTP 401 Unauthorized
Body: JSON error object

{
  "error": "unauthorized",
  "message": "Missing or invalid X-Ringba-Ping-Secret"
}

Upstream VICIdial Errors

Status: HTTP 503 Service Unavailable
Body: JSON object with conservative availability values.

{
  "available": false,
  "ready": 0,
  "logged_in": 0,
  "checked_at": "2026-08-26T16:52:03Z",
  "error": "vicidial_timeout"
}

7. Versioning & Change Notes

The API is intentionally minimal and stable. Changes are made rarely and coordinated between APFSC and Ringba support/engineering.

Version	Date	Notes
1.0	2026-08-26	Initial documentation of /ringba/agent-availability endpoint and VICIdial-backed semantics.

8. Security Considerations

• Endpoint is read-only and exposes only aggregate counts.
• No credentials, secret values, internal hostnames, or filesystem paths are returned.
• Authentication via X-Ringba-Ping-Secret header; must be stored and transmitted securely.
• HTTPS only; HTTP is not supported.
• APFSC may additionally restrict access using WAF/ACL rules.
• Callers should avoid logging full headers to prevent secret exposure.

9. Contact

For operational issues or questions about this integration, contact your APFSC technical point of contact or Ringba support, referencing the /ringba/agent-availability endpoint.