Finding a call recording with the recording_lookup API

When a manager or a QA tool needs the URL of a specific call, you do not want them logging into the admin screen and clicking through report pages. The Non-Agent API has a function for exactly this job: recording_lookup. You give it an agent, a date, or a lead id, and it hands back one line per recording with a direct link to the audio file.

What it does

The function searches the recording log and returns the Call recording entries that match your search fields. It is a read-only lookup — nothing on the dialer changes. You can search on any of these:

• agent_user — the agent login, 2 to 20 characters
• lead_id — the numeric lead id, 1 to 10 digits
• date — the day of the calls, in YYYY-MM-DD format
• uniqueid — the call's unique id (works best paired with another field)
• extension — 3 to 100 characters, the extension recorded in the log

One thing to know up front: the api user calling this needs user_level 7 or higher and the "view reports" permission enabled. Without it, the call is refused. If you are new to permission tiers, the user-level guide explains how those numbers map to functions.

A real example call

Here is a lookup for everything agent 1000 recorded on a given day. The source parameter is just a short label for who or what made the call — set it to something you will recognize in logs. The stage parameter picks the output format (csv, tab, json, or the default pipe).

http://your-server/vicidial/non_agent_api.php?source=test&function=recording_lookup&stage=pipe&user=6666&pass=1234&agent_user=1000&date=2010-12-03

A successful call does not print the word SUCCESS — it just prints the rows. Each line is pipe-delimited and ends with the file URL:

2010-12-03 12:00:01|1000|534820|876409|http://server/path/to/recording/20101203_120000_1234567890_1000-all.wav

The columns are start_time, user, recording_id, lead_id, and location. Add duration=Y and a duration-in-seconds column is inserted just before the location. The file extension reflects the system's Recording format (WAV/MP3), so if you store WAV you will see .wav links here.

How the request flows

sequenceDiagram
    participant QA as QA tool
    participant API as non_agent_api.php
    participant DB as recording_log
    participant FS as Audio store
    QA->>API: recording_lookup + search fields
    API->>API: check user_level >= 7
    API->>DB: match agent/date/lead_id
    DB-->>API: matching rows
    API->>FS: resolve file location
    API-->>QA: pipe rows with URL

Errors you will see

If the permission check fails you get ERROR: recording_lookup USER DOES NOT HAVE PERMISSION TO GET RECORDING INFO - 6666|0. A bad or empty set of search fields returns ERROR: recording_lookup INVALID SEARCH PARAMETERS, and a valid search with no hits returns ERROR: recording_lookup NO RECORDINGS FOUND. Treat the NO RECORDINGS line as an empty result, not a fault. The same parse rules apply to every Non-agent API function — there is more on that in reading API responses.

Practical notes

There is a hard limit of 100,000 results per call, so scope your searches to a single agent or day rather than pulling a whole month at once. Because the function returns file URLs, your Recording retention window matters — a lookup will happily return a row whose audio has already been pruned off disk, so the URL can 404. Match that retention policy to how far back your reviewers actually go.

On VICIfast every plan ships with the API (application programming interface) enabled and a dedicated box you fully control, so wiring a QA workflow to this function is just a matter of creating a reporting user. See the options on our pricing page.