Download of pcap files / audio files using GUI's api

From VoIPmonitor.org
Jump to navigation Jump to search


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:

  1. Use the `getVoipCalls` task with filters (like date range and caller number) to get a list of CDRs.
  2. 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?