Download of pcap files / audio files using GUI's api
This guide provides a comprehensive overview of how to programmatically download packet captures (PCAP) and audio recordings (WAV/OGG) from VoIPmonitor using its command-line API. It covers both single-file downloads and advanced scripting for bulk operations.
Introduction to the API
VoIPmonitor's GUI includes a powerful command-line interface located at `php/api.php` (in your GUI's web directory) that allows for the automation of tasks like downloading call data. The API accepts a JSON object via standard input and returns the requested file data to standard output, making it ideal for scripting.
All API requests share a common structure:
- `task`: The action to perform (e.g., `getPCAP`).
- `user`: A valid VoIPmonitor GUI username.
- `password`: The password for that user.
- `params`: An object containing the specific identifiers for the task.
Method 1: Downloading a Single File
This method is useful for fetching the data for one specific, known call.
How to Download a PCAP File
The `getPCAP` task retrieves the full packet capture for a single call. It requires the SIP `callId` and the exact `calldate`.
# Command to download the PCAP file for a specific call echo '{ "task": "getPCAP", "user": "admin", "password": "your_password", "params": { "callId": "ABC-123-XYZ@10.0.0.1", "calldate": "2023-10-26 14:30:00" } }' | php /var/www/html/php/api.php > /tmp/call_data.pcap
How to Download an Audio File (WAV/OGG)
The `getVoiceRecording` task generates and downloads the call's audio. It requires the call's unique numeric `cdrId`.
- To download a WAV file (default)
echo '{ "task": "getVoiceRecording", "user": "admin", "password": "your_password", "params": { "cdrId": "1186" } }' | php /var/www/html/php/api.php > /tmp/call_1186.wav
- To download an OGG file
Add the `ogg: "true"` parameter.
echo '{ "task": "getVoiceRecording", "user": "admin", "password": "your_password", "params": { "cdrId": "1186", "ogg": "true" } }' | php /var/www/html/php/api.php > /tmp/call_1186.ogg
Method 2: Bulk Downloading with a Script
For downloading audio from multiple calls that match certain criteria, you can use a script. The logic is always a two-step process:
- Use the `getVoipCalls` task with filters (like date range and caller number) to get a list of CDRs.
- Loop through the results and call `getVoiceRecording` for each `cdrId`.
Below are two PHP script examples that demonstrate this process.
Example 1: Bulk Download with Filenames as CDR ID
This script searches for all connected calls from a specific number in a date range and saves the audio files as `[CDR_ID].wav`.
<?php // --- Configuration --- $guiDir = "/var/www/html"; $batchDir = "/mnt/backups/audio_batch"; // Make sure this directory exists and is writable $user = "your_api_user"; $pass = "your_api_password"; // --- API Search Parameters --- $searchParams = [ "startTime" => "2023-01-01 00:00:00", "endTime" => "2023-02-01 00:00:00", "caller" => "0012345%", // Caller number starts with... "onlyConnected" => "1" ]; // --- Script Logic --- $requestPayload = json_encode([ "task" => "getVoipCalls", "user" => $user, "password"=> $pass, "params" => $searchParams ]); // Step 1: Get the list of CDRs exec("echo '" . addslashes($requestPayload) . "' | php " . $guiDir . "/php/api.php", $apiOutput, $returnVar); if ($returnVar === 0 && !empty($apiOutput)) { $response = json_decode($apiOutput[0]); $results = $response->cdr ?? []; $totalItems = count($results); echo "Found {$totalItems} calls to process.\n"; // Step 2: Loop through results and download each audio file foreach ($results as $index => $record) { $cdrId = $record->cdrId; echo "Processing CDR ID {$cdrId} (" . ($index + 1) . "/{$totalItems})...\n"; $downloadPayload = json_encode([ "task" => "getVoiceRecording", "user" => $user, "password"=> $pass, "params" => ["cdrId" => $cdrId] ]); exec("echo '" . addslashes($downloadPayload) . "' | php " . $guiDir . "/php/api.php > " . $batchDir . "/" . $cdrId . ".wav"); } echo "Bulk download complete.\n"; } else { echo "Error: Failed to retrieve call list from API.\n"; } ?>
Example 2: Bulk Download with Custom Filenames
This script does the same, but names the files using the format `calldate__caller__called.wav`.
<?php // --- Configuration --- $guiDir = "/var/www/html"; $batchDir = "/mnt/backups/audio_batch_custom"; $user = "admin"; $pass = "adminPassw"; // ... (API Search Parameters are the same as above) ... // --- Script Logic --- // ... (The 'getVoipCalls' part is the same as above) ... if ($returnVar === 0 && !empty($apiOutput)) { $response = json_decode($apiOutput[0]); $results = $response->cdr ?? []; $totalItems = count($results); echo "Found {$totalItems} calls to process.\n"; foreach ($results as $index => $record) { $cdrId = $record->cdrId; // Create a custom filename $filenameRaw = $record->calldate . "__" . $record->caller . "__" . $record->called; // Sanitize the filename by replacing forbidden characters with an underscore $charsToReplace = [':', ' ', '*', '#', '/']; $filenameSafe = str_replace($charsToReplace, "_", $filenameRaw); echo "Processing CDR ID {$cdrId} -> {$filenameSafe}.wav (" . ($index + 1) . "/{$totalItems})...\n"; $downloadPayload = json_encode([ "task" => "getVoiceRecording", "user" => $user, "password"=> $pass, "params" => ["cdrId" => $cdrId] ]); exec("echo '" . addslashes($downloadPayload) . "' | php " . $guiDir . "/php/api.php > " . $batchDir . "/" . $filenameSafe . ".wav"); } echo "Bulk download complete.\n"; } ?>
Performance Note for Large Batches
The simple PHP scripts above are single-threaded. They process one call at a time, which can be very slow for thousands of CDRs. For high-performance, large-scale batch downloads, a multi-threaded approach is necessary. Please see the more advanced Multi-threaded Batch Download Script for a solution designed for speed.
AI Summary for RAG
Summary: This guide provides a comprehensive tutorial on using the VoIPmonitor GUI's command-line API (`api.php`) to programmatically download call data. It is structured into two main methods. Method 1 covers downloading a single file, detailing the `getPCAP` task (which requires `callId` and `calldate`) and the `getVoiceRecording` task (which requires `cdrId`) for both WAV and OGG formats. Method 2 focuses on bulk downloading and provides two complete PHP script examples. These scripts demonstrate a two-step workflow: first, using the `getVoipCalls` API task with search filters to retrieve a list of call IDs, and second, looping through these IDs to download each audio file using the `getVoiceRecording` task. The examples show how to save files with either the CDR ID as the filename or a custom filename format (`calldate__caller__called`). Finally, it includes a performance note advising that these simple scripts are single-threaded and points to a dedicated multi-threaded script for large-scale operations. Keywords: api, command line, cli, script, automation, bulk download, batch, `api.php`, JSON, `getVoipCalls`, `getPCAP`, `getVoiceRecording`, download audio, search cdr, filter, php, exec Key Questions:
- How can I automate downloading of audio or PCAP files from VoIPmonitor?
- Is there a script to bulk download all calls matching certain criteria?
- How do I use the `api.php` to search for calls and then download them?
- How can I name downloaded audio files based on caller/called number and date?
- Why is my PHP bulk download script slow?
- How to use the VoIPmonitor API from a PHP script?
- What is the difference between `callId` and `cdrId` in the API?