VICIdial is a powerful open-source call center solution used worldwide for managing inbound, outbound, and blended campaigns. Ensuring that agents have access to the right campaigns is crucial for effective call routing, agent productivity, and campaign management.
The agent_campaigns API allows administrators to retrieve a list of campaigns assigned to a specific agent, making it an essential tool for real-time campaign access management, CRM integrations, and agent monitoring.
Why Use the agent_campaigns API?
✅ Retrieve assigned campaigns for an agent in real-time
✅ Ensure proper campaign access based on agent roles
✅ Integrate VICIdial campaign data with third-party CRM systems
✅ Automate agent access verification for security and compliance
In this guide, we will cover:
🔹 What the agent_campaigns API does
🔹 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 agent_campaigns API efficiently
Let’s dive in! 🚀
Understanding the agent_campaigns API Function
The agent_campaigns API allows administrators to retrieve all campaigns assigned to a specific agent.
What Information Does the agent_campaigns API Provide?
✔ A list of all campaigns assigned to an agent
✔ Campaign IDs and campaign names
✔ The current agent user ID and their access level
Common Use Cases for agent_campaigns API
🔹 Verify which campaigns an agent can access
🔹 Automatically assign agents to the correct campaigns
🔹 Integrate with CRMs to filter leads based on agent access
🔹 Generate reports on agent campaign assignments
Step 1: Prerequisites for Using the API
Before using the agent_campaigns API, ensure you have the following:
✅ VICIdial installed and configured
✅ An API-enabled user account with administrative permissions
✅ A valid agent user ID to retrieve campaign access
✅ 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 agent_campaignsto the **Allowed API Functions** (or set toALL`)
7️⃣ Click Save Changes
Now, your user is authorized to retrieve campaign access details 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 agent_campaigns API
| Parameter | Description | Example |
|---|---|---|
function |
Specifies the API function (agent_campaigns) |
agent_campaigns |
user |
VICIdial API username | admin |
pass |
VICIdial API password | 1234 |
source |
Identifier for tracking API calls | CRM_AgentAccess |
agent_user |
The user ID of the agent to check | agent001 |
Step 3: Sending the API Request
Method 1: Retrieving Campaign Access via a Web Browser
Simply enter the following URL in your browser (replace credentials accordingly):
🔹 Press Enter, and the API response should display the agent’s campaign access details.
Method 2: Retrieving Campaign Access via cURL (Command Line)
For developers, cURL is a convenient tool for making API requests. Use the following command:
🔹 This will return the campaign list assigned to the agent in the terminal.
Method 3: Retrieving Campaign Access via Postman
1️⃣ Open Postman
2️⃣ Set the request type to GET
3️⃣ Enter the API URL
4️⃣ Click Send
5️⃣ View the API response in the output panel
Step 4: Understanding API Responses
If the request is successful, VICIdial returns a response listing the campaigns assigned to the agent:
Breaking Down the Response
| Value | Meaning |
|---|---|
agent001 |
The agent’s user ID |
Campaign1 |
The first campaign assigned to the agent |
Outbound Sales |
The campaign name |
Campaign2 |
The second campaign assigned to the agent |
Inbound Support |
The campaign name |
Step 5: Handling Errors & Troubleshooting
If something goes wrong, VICIdial will return an error message instead of campaign details.
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: NO FUNCTION SPECIFIED |
Missing function parameter | Ensure function=agent_campaigns is included |
ERROR: AGENT NOT FOUND |
The agent user ID does not exist | Verify that the agent_user exists in VICIdial |
Step 6: Best Practices for Using the agent_campaigns API
✅ Use this API to ensure agents have correct campaign assignments
✅ Integrate campaign access data with CRM systems for call routing
✅ Automate campaign assignment verification for agent onboarding
✅ Log API calls to track agent campaign access history
✅ Monitor API usage to detect errors and optimize performance
Conclusion
The agent_campaigns API function is an essential tool for tracking agent campaign assignments in VICIdial. Whether you’re managing live campaigns, integrating VICIdial with CRMs, or ensuring agents have the right campaign access, this API provides quick and accurate campaign retrieval.
📌 Key Takeaways
✅ The agent_campaigns API retrieves an agent’s assigned campaigns
✅ Requires an API-enabled user with appropriate permissions
✅ API requests can be made via browser, cURL, or Postman
✅ Common errors are permission and input-related and can be fixed in Admin settings
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
