Managing phone aliases in VICIdial allows administrators to assign multiple identifiers to a single phone extension, improving flexibility in agent routing, call handling, and VoIP configurations. Instead of manually configuring alias records in the VICIdial Admin Panel, administrators can use the add_phone_alias API to dynamically create phone aliases, streamlining operations and enabling real-time updates.
What is a Phone Alias in VICIdial?
A phone alias allows a single SIP or IAX2 phone extension to have multiple alias names or numbers, helping with:
✅ Routing calls through different identifiers
✅ Handling multiple agent logins through a single phone device
✅ Configuring backup phone extensions for call redundancy
✅ Improving call tracking and agent management
Why Use the add_phone_alias API?
✅ Dynamically create phone aliases without manual entry
✅ Enable seamless call routing across multiple aliases
✅ Reduce downtime and improve call management flexibility
✅ Integrate with external VoIP/PBX systems for alias management
✅ Improve redundancy by assigning backup aliases for agents
In this tutorial, we will cover:
🔹 How the add_phone_alias 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 add_phone_alias API efficiently
Let’s get started! 🚀
Understanding the add_phone_alias API Function
The add_phone_alias API allows administrators to create a new phone alias in VICIdial, which is mapped to an existing phone extension.
What Information Does the add_phone_alias API Require?
✔ Alias Name – The unique identifier for the alias
✔ Extension – The phone extension to which the alias will be mapped
✔ Protocol Type – SIP or IAX2
✔ Active Status – Enable (Y) or disable (N) the alias
✔ Source – A custom identifier for tracking API calls
Common Use Cases for add_phone_alias API
🔹 Assigning multiple aliases to a single phone for call tracking
🔹 Configuring backup aliases for agents using multiple extensions
🔹 Integrating alias management with external VoIP systems
🔹 Setting up test aliases for call routing analysis
🔹 Improving failover and call redundancy in call centers
Step 1: Prerequisites for Using the API
Before using the add_phone_alias API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid phone extension that the alias will be mapped to
✅ 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 add_phone_aliasto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to create new phone aliases dynamically 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 add_phone_alias API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_phone_alias) |
add_phone_alias |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | PhoneAliasUpdate |
alias |
The unique alias name | SupportDesk |
extension |
The phone extension mapped to this alias | 1001 |
protocol |
Protocol type (SIP or IAX2) | SIP |
active |
Enable (Y) or disable (N) the alias |
Y |
Step 3: Sending the API Request
Method 1: Creating a Phone Alias via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should create the new alias.
Method 2: Creating a Phone Alias via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a confirmation message indicating the alias has been created.
Method 3: Creating a Phone Alias via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ The response should display the confirmation message for the new alias
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the alias creation:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
SupportDesk |
The alias name created |
Alias Created Successfully for Extension 1001 |
Confirmation message |
Step 5: Handling Errors & Troubleshooting
| 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: ALIAS NAME ALREADY EXISTS |
The alias is already in use | Choose a unique alias name |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_phone_alias is included |
Step 6: Best Practices for Using the add_phone_alias API
✅ Ensure alias names are unique to prevent conflicts
✅ Restrict API access to prevent unauthorized alias creation
✅ Use meaningful alias names for better tracking and call management
✅ Regularly audit alias records to maintain database integrity
✅ Integrate alias management with VoIP and PBX systems
Conclusion
The add_phone_alias API function is an essential tool for dynamically managing phone aliases in VICIdial. Whether you’re assigning backup aliases, optimizing call routing, or integrating with external systems, this API provides a fast and efficient way to enhance call center operations.
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
