In a call center environment, managing SIP phones, extensions, and softphones efficiently is crucial for agent productivity, call routing, and seamless communication. VICIdial, a leading open-source call center solution, allows administrators to add new phone extensions dynamically using the add_phone API.
Instead of manually adding phone extensions via the VICIdial Admin Panel, this API enables automated provisioning of new phones, helping IT teams and call center administrators save time, reduce errors, and integrate with external provisioning systems.
Why Use the add_phone API?
✅ Automate phone provisioning for new agents
✅ Reduce manual configuration efforts for softphones and SIP devices
✅ Ensure seamless onboarding of agents with pre-configured phone settings
✅ Enable real-time phone extension creation for remote workers
✅ Integrate with external VoIP and telephony management systems
In this tutorial, we’ll cover:
🔹 How the add_phone 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 API efficiently
Let’s get started! 🚀
Understanding the add_phone API Function
The add_phone API allows administrators to create a new phone extension in VICIdial, which can be used for softphones, SIP devices, and VoIP phones.
What Information Does the add_phone API Require?
✔ Extension – The unique identifier for the phone extension
✔ Protocol Type – SIP or IAX2 (Inter-Asterisk eXchange)
✔ Phone Pass – The password for the phone extension
✔ Server IP – The VICIdial server handling the phone registration
✔ Active Status – Whether the phone is active (Y) or inactive (N)
✔ Registration Status – Determines if the phone should be registered with Asterisk
Common Use Cases for add_phone API
🔹 Provisioning new SIP or softphone extensions automatically
🔹 Integrating phone management with an external PBX system
🔹 Onboarding new agents remotely with pre-configured softphones
🔹 Bulk-adding new phone extensions for large-scale deployments
🔹 Creating phone extensions dynamically for VoIP services
Step 1: Prerequisites for Using the API
Before using the add_phone API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid extension name and SIP/IAX2 configuration details
✅ 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_phoneto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to add new phone extensions 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 API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_phone) |
add_phone |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | PhoneProvisioning |
extension |
The phone extension (unique ID) | 1001 |
protocol |
SIP or IAX2 | SIP |
server_ip |
VICIdial server handling registration | 192.168.1.10 |
pass |
Password for phone authentication | securepass123 |
active |
Enable (Y) or disable (N) the extension |
Y |
registration |
Determines if the phone is registered (Y) or not (N) |
Y |
Step 3: Sending the API Request
Method 1: Adding a New Phone via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should create the new phone extension.
Method 2: Adding a New Phone 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 phone extension has been added.
Method 3: Adding a New Phone 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 phone extension
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the new phone has been created:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
1001 |
The phone extension created |
Phone Extension Created Successfully |
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: EXTENSION ALREADY EXISTS |
The extension is already in use | Choose a unique extension number |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_phone is included |
Step 6: Best Practices for Using the add_phone API
✅ Ensure unique extension numbers to avoid conflicts
✅ Use strong passwords for SIP/IAX2 authentication
✅ Restrict API access to prevent unauthorized phone provisioning
✅ Integrate with VoIP management systems for automation
✅ Regularly review and audit phone extensions for security compliance
Conclusion
The add_phone API function is an essential tool for adding new phone extensions dynamically in VICIdial. Whether you’re automating SIP provisioning, integrating with VoIP systems, or setting up new call center agents, this API provides a fast and efficient way to manage phone extensions.
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
