Inbound Direct Inward Dialing (DID) numbers are essential for call centers handling inbound calls, allowing customers to reach agents directly without navigating IVRs or shared numbers. VICIdial, a leading open-source call center solution, provides the add_did API, which allows administrators to add new DIDs dynamically without manually configuring them in the VICIdial admin panel.
The add_did API helps call centers automate DID management, ensuring seamless call routing, campaign integration, and real-time updates. Instead of manually configuring DIDs for every inbound campaign, businesses can automate DID provisioning via API, improving efficiency, scalability, and accuracy.
Why Use the add_did API?
✅ Automate DID setup without manual configuration
✅ Integrate DIDs with third-party CRM or telephony systems
✅ Quickly assign inbound numbers to specific campaigns
✅ Enhance call routing flexibility by dynamically configuring DIDs
✅ Reduce errors and streamline inbound call handling
In this tutorial, we’ll cover:
🔹 How the add_did 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_did API efficiently
Let’s get started! 🚀
Understanding the add_did API Function
The add_did API allows administrators to create and assign inbound DID numbers dynamically, ensuring that calls are routed to the correct agents, campaigns, or IVRs.
What Information Does the add_did API Require?
✔ DID Pattern – The phone number being assigned
✔ DID Route – The call destination (AGENT, CALLMENU, EXTEN, VOICEMAIL, etc.)
✔ Campaign ID – The campaign assigned to the DID (if applicable)
✔ User ID – The agent or group receiving calls
✔ Voicemail Box – The voicemail box assigned to the DID (if applicable)
✔ Active Status – Whether the DID is active (Y) or inactive (N)
✔ Custom Call Menu – Route calls to a specific IVR menu
Common Use Cases for add_did API
🔹 Automating inbound number provisioning for campaigns
🔹 Assigning specific DID numbers to dedicated sales teams
🔹 Integrating VICIdial with external SIP trunk providers
🔹 Dynamically updating call routing rules based on business needs
🔹 Providing local DIDs for better customer engagement
Step 1: Prerequisites for Using the API
Before using the add_did API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid DID number to add
✅ 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_didto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to add inbound DIDs 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_did API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (add_did) |
add_did |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | DIDSetup |
did_pattern |
The phone number to configure | 18001234567 |
did_description |
A brief description of the DID | Support Line |
did_route |
The call destination (AGENT, CALLMENU, etc.) |
AGENT |
user_id |
(Optional) Agent ID if routing calls to an agent | 1001 |
group_id |
(Optional) Call group for inbound routing | SUPPORT_TEAM |
voicemail_ext |
(Optional) Assign a voicemail box | 8500 |
did_active |
Enable (Y) or disable (N) the DID |
Y |
Step 3: Sending the API Request
Method 1: Adding a DID via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should create the new inbound DID.
Method 2: Adding a DID via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return a success message confirming the DID creation.
Method 3: Adding a DID via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ The response should confirm that the DID has been added
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the DID was added:
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
18001234567 |
The DID number that was added |
DID Added Successfully |
Confirmation message |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of a success confirmation.
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: DID ALREADY EXISTS |
The DID is already configured | Choose a unique did_pattern |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=add_did is included |
Conclusion
The add_did API function is an essential tool for automating inbound call routing in VICIdial. Whether you’re integrating with external SIP providers, managing high-volume inbound campaigns, or assigning dedicated agent numbers, this API provides a fast and efficient way to configure DIDs dynamically.
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
