Pulling a disposition report with call_dispo_report

The call_dispo_report function is a Non-agent API call that returns a count of calls broken down by Disposition for the campaigns, ingroups, or DIDs you ask about. If you want disposition totals in your own reporting tool without scraping the VICIdial report screens, this is the cleanest way to get them. For the bigger map of what the API (application programming interface) can do, read the VICIdial API overview.

When you'd use it

Use it for a nightly ETL job that loads disposition counts into a warehouse, or for a CRM widget that shows how an Ingroup performed over the past week. Because you can target a specific DID (direct inward dialing), it is also handy for measuring a single marketing number across a campaign period. You pass a date range and, optionally, a list of statuses, and the dialer does the grouping for you.

How the call works

sequenceDiagram
  participant App
  participant API as non_agent_api.php
  participant V as VICIdial DB
  App->>API: call_dispo_report (ingroups, query_date, end_date)
  API->>V: verify user_level 9 and view reports
  API->>V: aggregate calls by disposition
  V-->>API: grouped counts
  API-->>App: CSV-style rows of totals

You hit non_agent_api.php with your filters. VICIdial checks permissions, runs the aggregation over the chosen date range, and returns comma-separated rows. There is no SUCCESS keyword; the data itself is the success response.

Parameters

• campaigns OR ingroups OR dids — one of these is required. Use single-dash delimiters for more than one, like TEST_IN3-TEST_IN2.
• query_date — optional start date in YYYY-MM-DD format. Leave blank to default to today.
• end_date — optional end date in YYYY-MM-DD format. Leave blank to default to today.
• statuses — optional list of specific statuses, dash-delimited. Leave blank for all.
• categories — optional list of status categories, dash-delimited. Leave blank for all.
• users — optional list of specific users, single-dash delimited.
• status_breakdown — 0 or 1. Set 1 to break the totals out by individual status. Default 0.
• show_percentages — 0 or 1. Only works when status_breakdown is on; adds a percentage next to each count. Default 0.
• file_download — 0 or 1. Set 1 to return the result as a downloadable CSV file. Default 0.

An example call

http://server/vicidial/non_agent_api.php?source=test&user=6666&pass=1234&function=call_dispo_report&ingroups=TEST_IN3-TEST_IN2&query_date=2018-02-05&end_date=2018-02-07&status_breakdown=1&show_percentages=1

Without status_breakdown you get a simple two-column total per element:

CAMPAIGN,TOTAL CALLS
TEST_IN2,10
TEST_IN3,110
TOTAL,120

Turn status_breakdown on and each status becomes its own column. Add show_percentages and each cell carries a percentage:

CAMPAIGN,TOTAL CALLS,ACFLTR,NP,WAITTO,CLOSOP,DROP,INCALL,RQXFER,TD,TESTAM
TEST_IN2,10,1 (10.0%),0 (0.0%),0 (0.0%),0 (0.0%),5 (50.0%),0 (0.0%),0 (0.0%),0 (0.0%),4 (40.0%)
TEST_IN3,110,0 (0.0%),5 (4.5%),13 (11.8%),9 (8.2%),3 (2.7%),1 (0.9%),47 (42.7%),1 (0.9%),31 (28.2%)
TOTAL,120,1 (0.8%),5 (4.2%),13 (10.8%),9 (7.5%),8 (6.7%),1 (0.8%),47 (39.2%),1 (0.8%),35 (29.2%)

Permissions and gotchas

This one is stricter than most reporting calls: the API user must have user_level set to exactly 9 and view reports enabled. Miss it and you get ERROR: call_dispo_report USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION. Forget to pass any of campaigns, ingroups, or dids and you get ERROR: call_dispo_report INVALID OR MISSING CAMPAIGNS, INGROUPS, OR DIDS. The other trap is the delimiter: this function uses single dashes between items, not pipes, which is the opposite of several other Non-Agent calls. If you want call counts with hourly breakdowns instead of disposition columns, the related read is covered in the call status stats API guide.

On a VICIfast box the Non-Agent API is ready the moment your server goes Status (lead status) active, so you can wire disposition reporting into your stack on day one. See our pricing to spin one up.