As businesses embrace remote work and distributed call center operations, managing remote agents efficiently becomes crucial. VICIdial, a powerful open-source call center solution, offers the update_remote_agent API, allowing administrators to modify remote agent settings dynamically without manual configuration through the Admin Panel.
This API is designed to help call center managers and VoIP administrators automate agent assignment, modify remote agent extensions, and control login/logout behavior dynamically, ensuring a flexible, scalable, and well-managed remote workforce.
Why Use the update_remote_agent API?
✅ Modify remote agent settings dynamically without manual intervention
✅ Adjust remote agent call limits, campaigns, and active status instantly
✅ Enable or disable remote agents in real time
✅ Integrate with external CRM and workforce management tools
✅ Automate agent provisioning for remote and hybrid teams
In this tutorial, we will cover:
🔹 How the update_remote_agent 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 update_remote_agent API efficiently
Let’s get started! 🚀
Understanding the update_remote_agent API Function
The update_remote_agent API allows administrators to modify settings for remote agents dynamically in VICIdial, including agent call limits, status, campaigns, and extension details.
What Information Can Be Updated Using update_remote_agent API?
✔ User ID – Modify settings for a specific remote agent
✔ Call Limit – Adjust the number of concurrent calls the agent can handle
✔ Campaign ID – Assign or change the campaign the remote agent is handling
✔ Status – Enable (ACTIVE) or disable (INACTIVE) the remote agent
✔ Extension – Modify the agent’s phone extension
✔ Delete Agent – Remove a remote agent from the system
Common Use Cases for update_remote_agent API
🔹 Enabling or disabling remote agents dynamically
🔹 Modifying campaign assignments for remote agents in real time
🔹 Adjusting call concurrency limits based on workload and call volume
🔹 Automating agent status updates via workforce management tools
🔹 Removing inactive agents from VICIdial for better resource management
Step 1: Prerequisites for Using the API
Before using the update_remote_agent API, ensure you have:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions**
✅ A valid remote agent ID that exists in VICIdial
✅ 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 update_remote_agentto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to modify remote agent settings 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 update_remote_agent API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (update_remote_agent) |
update_remote_agent |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | RemoteAgentUpdate |
remote_agent_id |
The unique ID of the remote agent | 2001 |
call_limit |
The max number of concurrent calls the agent can handle | 3 |
campaign_id |
The campaign assigned to the remote agent | SALES_CAMPAIGN |
status |
Activate (ACTIVE) or deactivate (INACTIVE) the agent |
ACTIVE |
extension |
The phone extension assigned to the agent | SIP/1001 |
delete_agent |
(Optional) Delete the agent (Y to delete) |
N |
Step 3: Sending the API Request
Method 1: Updating a Remote Agent via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API should modify the remote agent’s settings.
Method 2: Updating a Remote Agent 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 agent settings have been updated.
Method 3: Deleting a Remote Agent via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL with delete_agent=Y
4️⃣ Click Send
5️⃣ The response should confirm that the remote agent was removed
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response confirming the update:
OR
Breaking Down the Response
| Response Value | Meaning |
|---|---|
SUCCESS |
The request was processed successfully |
2001 |
The remote agent ID modified |
Remote Agent Updated 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: REMOTE AGENT NOT FOUND |
The specified agent ID does not exist | Ensure remote_agent_id is correct |
ERROR: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=update_remote_agent is included |
Conclusion
The update_remote_agent API function is an essential tool for managing remote agent configurations dynamically in VICIdial. Whether you’re modifying agent settings, updating campaign assignments, enabling/disabling agents, or deleting inactive users, this API provides a fast and efficient way to optimize your remote workforce.
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
