Call recordings are crucial for quality assurance, compliance, dispute resolution, and agent training in call centers. VICIdial, a powerful open-source call center solution, provides the ability to retrieve call recordings based on date or lead ID using the recording_lookup API.
The recording_lookup API enables administrators, managers, and compliance officers to search and retrieve call recordings efficiently, making it easier to audit calls, verify interactions, and integrate with third-party CRM or reporting systems.
Why Use the recording_lookup API?
✅ Retrieve call recordings quickly based on a specific date or lead ID
✅ Ensure compliance with legal and regulatory requirements
✅ Verify customer interactions and dispute resolutions
✅ Monitor and improve agent performance through recorded calls
✅ Integrate call recordings with external CRM or analytics tools
In this tutorial, we will cover:
🔹 How the recording_lookup API works
🔹 How to configure and authenticate API access
🔹 How to construct and send API requests
🔹 Examples using a browser, cURL, and Postman
🔹 How to interpret API responses and troubleshoot errors
🔹 Best practices for using the recording_lookup API efficiently
Let’s get started! 🚀
Understanding the recording_lookup API Function
The recording_lookup API allows administrators and supervisors to search for call recordings by:
✔ Date – Retrieve all recordings for a specific day
✔ Lead ID – Retrieve recordings associated with a particular lead
✔ Campaign ID – (Optional) Filter recordings by campaign
Common Use Cases for recording_lookup API
🔹 Managers retrieving call recordings for agent evaluation
🔹 Compliance officers searching recordings for legal requirements
🔹 Quality assurance teams verifying customer interactions
🔹 CRM systems integrating VICIdial recordings for better customer insights
Step 1: Prerequisites for Using the API
Before using the recording_lookup API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions
✅ A valid date or lead ID to search recordings
✅ VICIdial server access credentials
How to Enable API Access in VICIdial
1️⃣ Log in to the VICIdial Admin Panel
2️⃣ Navigate to Admin > Users
3️⃣ Select the user who will access the API
4️⃣ Set API Access to 1 (Enabled)
5️⃣ Set User Level to 8 or higher** (Admin-level access) 6️⃣ Add recording_lookupto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve call recordings using the API.
Step 2: Constructing the API Request
The VICIdial API uses HTTP GET requests, meaning you can access it via a browser, cURL, or API tools like Postman.
Base API URL
🔹 Replace your-vicidial-server with your actual VICIdial instance.
Required Parameters for recording_lookup API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (recording_lookup) |
recording_lookup |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CallAudit |
date |
(Optional) The date of recordings to retrieve | 2024-02-10 |
lead_id |
(Optional) The Lead ID for recordings | 1001 |
Step 3: Sending the API Request
Method 1: Fetching Recordings via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API response should display a list of recordings for the specified date.
To search by Lead ID, use:
Method 2: Fetching Recordings via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a list of call recordings for the specified date.
Method 3: Fetching Recordings via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ View the API response in the output panel
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response listing the call recordings:
Breaking Down the Response
| Value | Meaning |
|---|---|
1001 |
Lead ID |
2024-02-10 |
Recording Date |
agent001 |
Agent User ID |
Outbound Sales |
Campaign Name |
rec_1001_20240210.wav |
Recording File Name |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of a list of recordings.
Common Errors & Fixes
| Error Message | Cause | Solution |
|---|---|---|
ERROR: USER DOES NOT HAVE PERMISSION TO USE THIS FUNCTION |
Insufficient API permissions | Ensure user level is 8+ and API Access is enabled |
ERROR: INVALID USERNAME OR PASSWORD |
Wrong credentials | Verify API username and password |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=recording_lookup is included |
ERROR: NO RECORDINGS FOUND |
No recordings exist for the date/lead ID | Verify that the specified date or lead ID is correct |
Step 6: Best Practices for Using the recording_lookup API
✅ Use this API for compliance and auditing purposes
✅ Ensure API users have proper permissions to prevent unauthorized access
✅ Integrate call recordings with CRM systems for better customer management
✅ Log API calls to track usage and prevent misuse
✅ Regularly archive recordings to optimize database performance
Conclusion
The recording_lookup API function is an essential tool for tracking call recordings in VICIdial. Whether you’re retrieving recordings for quality assurance, compliance checks, or CRM integration, this API provides quick and accurate access to historical call data.
📌 Key Takeaways
✅ The recording_lookup API retrieves VICIdial call recordings by date or Lead ID
✅ Requires an API-enabled user with appropriate permissions
✅ API requests can be made via browser, cURL, or Postman
✅ Common errors are permission and input-related and can be fixed in Admin settings
Feel free to contact us or simply start a live chat to get connected to one of our team members. Here is our contact information.
Calling from US: +1 954-990-0053
Email: office@callix.ai
