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?