Reading live call-status counts with call_status_stats

For a wallboard or a quick health check, you do not want full call logs - you want counts. How many calls today, how many got a human, broken down by hour and by result. The Non-Agent API function call_status_stats returns exactly that: per-campaign and per-ingroup call counts with hourly and status breakdowns.

Required and optional fields

One field is required:

• campaigns - use ---ALL--- or ALLCAMPAIGNS for all, or dash-delimit several (TESTCAMP-TESTCAMP2)

Three optional fields narrow the result:

• query_date - the day to report on (YYYY-MM-DD), defaults to today
• ingroups - dash-delimited list of inbound groups; blank means all ingroups in the chosen campaigns
• statuses - dash-delimited list of statuses; blank means all

This one wants a higher permission tier than the export functions: the api user needs user_level 8 or higher with "view reports" enabled. An Ingroup, for the newcomer, is an inbound call group - the queue that received calls get sorted into.

A real example call

Here is a request for all campaigns and ingroups for one day:

http://your-server/vicidial/non_agent_api.php?user=6666&pass=1234&function=call_status_stats&campaigns=---ALL---&query_date=2017-11-24

And a narrower one - two campaigns, one ingroup, only NP and TD statuses:

http://your-server/vicidial/non_agent_api.php?user=6666&pass=1234&function=call_status_stats&campaigns=TESTCAMP-TESTCAMP2&query_date=2017-11-24&statuses=NP-TD&ingroups=AGENTDIRECT

A successful call prints no SUCCESS line, just one pipe-delimited row per campaign or ingroup:

campaign_id/ingroup|total calls|human answered calls|hourly breakdown|status breakdown

TESTCAMP|26|26|00-0,01-1,02-1,...,21-6,22-1,23-1|NP-4,TD-22|

Inside a row, the hourly breakdown is a comma-list of HH-count pairs (so 21-6 means six calls in the 9 PM hour), and the status breakdown is a comma-list of status-count pairs (TD-22 means 22 calls dispositioned TD). That structure makes it easy to drive a per-hour chart and a status pie from one cheap call.

Live counts feeding a dashboard

flowchart LR
    A[call_status_stats] --> B[total calls]
    A --> C[human answered]
    A --> D[hourly breakdown]
    A --> E[status breakdown]
    B --> F[Wallboard]
    C --> F
    D --> G[Per-hour chart]
    E --> H[Status pie]
    F --> I[Ops view]
    G --> I
    H --> I

Errors to handle

If you forget the required field you get ERROR: call_status_stats INVALID OR MISSING CAMPAIGNS. A user who is not allowed to call the function at all gets ERROR: auth USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION, and a user who can call it but lacks the view-stats right gets ERROR: call_status_stats USER DOES NOT HAVE PERMISSION TO VIEW STATS. As with every Non-agent API function, read the first token and branch if it starts with ERROR - the same habit covered in reading API responses.

For historical per-agent numbers rather than live counts, pair this with agent_stats_export. Every VICIfast box has the full API (application programming interface) turned on, so wiring a wallboard to these counts is straightforward - see what each plan includes on the pricing page.