VICIdial is an open-source contact center solution that allows businesses to manage inbound and outbound calls efficiently. One essential aspect of VICIdial is its ability to manage audio files, which can be used for music on hold, pre-recorded messages, IVR prompts, and agent guidance. This tutorial will walk you through the process of fetching available audio files using VICIdial’s Non-Agent API.
Understanding the sounds_list API Endpoint
The sounds_list function in the VICIdial Non-Agent API allows users to retrieve a list of available audio files stored in the system. These audio files are typically used for call recordings, IVR messages, music on hold, and custom announcements.
API Endpoint
http://your-vicidial-server/vicidial/non_agent_api.php?function=sounds_list
Required Parameters
| Parameter | Type | Description |
|---|---|---|
source |
String | A short identifier for the API call, e.g., “myapp” |
user |
String | VICIdial user with API access |
pass |
String | Password for the VICIdial user |
function |
String | The API function, in this case, sounds_list |
Optional Parameters
| Parameter | Type | Description |
|---|---|---|
format |
String | Defines output format (tab, link, selectframe) |
stage |
String | Sorting method (date, size, name) |
comments |
String | The field to populate with the file name |
Example API Request
To retrieve a list of available audio files, make a GET request to:
http://your-vicidial-server/vicidial/non_agent_api.php?source=myapp&user=admin&pass=1234&function=sounds_list&format=tab&stage=name
Example Response
If the request is successful, the response will be a list of available audio files. Here’s an example response:
SUCCESS
welcome_message.wav
goodbye_message.wav
hold_music.mp3
ivr_prompt.wav
Handling Errors
In case of an error, the API will return an appropriate error message. Here are some common error responses:
| Error Message | Possible Cause |
|---|---|
ERROR: sounds_list USER DOES NOT HAVE PERMISSION TO VIEW SOUNDS LIST |
The user lacks the required permissions |
ERROR: audio store web directory does not exist |
The server cannot find the directory where audio files are stored |
ERROR: sounds_list CENTRAL SOUND CONTROL IS NOT ACTIVE |
The VICIdial configuration does not have central sound control enabled |
Using the Data in Your Application
The response data can be used in various ways, such as:
- Displaying a list of available audio files in your custom VICIdial dashboard
- Selecting an IVR prompt dynamically from the retrieved list
- Assigning pre-recorded messages to outbound calls automatically
Advanced Usage: Filtering and Sorting
To fetch the list in different formats or sorted in a particular order, use the format and stage parameters:
Sorting by Name
http://your-vicidial-server/vicidial/non_agent_api.php?source=myapp&user=admin&pass=1234&function=sounds_list&stage=name
Sorting by Date
http://your-vicidial-server/vicidial/non_agent_api.php?source=myapp&user=admin&pass=1234&function=sounds_list&stage=date
Fetching as Selectable List for UI
http://your-vicidial-server/vicidial/non_agent_api.php?source=myapp&user=admin&pass=1234&function=sounds_list&format=selectframe
Conclusion
The sounds_list API function in VICIdial is an essential tool for managing and retrieving audio files efficiently. Whether you’re setting up IVR messages, customizing call flows, or monitoring available audio assets, this API simplifies the process. By integrating this functionality into your system, you can enhance your call center’s automation and efficiency.
For advanced integrations, consider combining this API with other VICIdial APIs to create a seamless experience. Happy coding!
Frequently Asked Questions (FAQs)
1. What user level is required to access the sounds_list API?
The user must have a level of 7 or higher to access this API function.
2. Can I use HTTPS for API calls?
Yes, if your VICIdial server is configured for HTTPS, the API calls will work securely.
3. How can I troubleshoot an empty response?
- Ensure the user has the correct permissions.
- Check if there are any audio files stored in the VICIdial server.
- Verify that the
formatandstageparameters are correctly set.
4. Is it possible to delete audio files using the API?
No, the sounds_list API only retrieves the list of available audio files. Deleting files must be done manually through the VICIdial admin panel or server shell.
5. Can I use this API in a custom dashboard?
Yes, developers can integrate this API into their dashboards to allow users to select and manage audio files dynamically.
Outro
By leveraging the sounds_list API, VICIdial users can efficiently manage their audio assets, enhancing both customer interactions and operational efficiency. Whether you’re a call center manager, developer, or administrator, mastering this API is a key step in optimizing your VICIdial environment.
If you’re interested in learning more about VICIdial APIs, stay tuned for our upcoming tutorials on integrating VICIdial with other systems, automating call flows, and optimizing agent productivity.
Need help with VICIdial implementation or custom API integrations? Contact us today and let our experts assist you!
