Category: Vicidial Software Solutions

A default VICIdial agent screen was built for a single dialer, a single script, and a small operations team. A custom VICIdial theme fixes everything at the interface layer, without touching the dialer logic underneath.

Drop that same screen into a BPO floor running eight or ten campaigns at once, and the cracks show fast: agents lose track of which campaign they’re logged into, supervisors can’t read status at a glance, and every new client onboarding means retraining staff on a layout that never changed to fit the work. 

This guide walks through what a custom VICIdial theme actually does, how it’s built for multi-campaign floors specifically, and how to diagnose the agent-side issues that a poorly built theme tends to hide rather than fix.

What a custom VICIdial theme actually changes

VICIdial ships with a default agent interface (vicidial.php) built on older PHP templates. That distinction matters for BPO decision-makers. Theming is a front-end project. It doesn’t require rewriting predictive dialing logic, hopper behavior, or lead scoring. It changes what the agent sees and how many clicks stand between them and a disposition.

For a single-campaign setup, this is a nice-to-have. For a multi-campaign floor, it’s closer to a requirement. Agents rotating between campaigns during a shift, or handling blended queues, need the screen to tell them instantly which script, which client, and which compliance rules apply to the call in front of them.

Why multi-campaign floors expose the default interface’s limits

A few patterns show up repeatedly once a BPO scales past two or three active campaigns on one server:

• Agents misidentify the active campaign mid-shift, especially during blended inbound and outbound queues, and read from the wrong script.

• Disposition lists grow long and generic across campaigns, so agents scroll or search instead of clicking the correct code in one motion.

• Supervisors monitoring the floor can’t distinguish which agents sit on which campaign without opening a separate report, because the default screen gives campaign context low visual priority.

• New client onboarding takes longer than it should, because every campaign addition means agents relearning a static layout that was never designed to flex.

• None of these are dialer bugs. They’re workspace design problems, and they’re exactly what a custom theme is built to solve.

Core elements of an efficient multi-campaign agent workspace

A theme built specifically for multi-campaign BPO work tends to include the following, regardless of which agency builds it:

Campaign-aware header bar

The active campaign name, client identifier, and script version sit in a fixed, color-coded position that changes automatically when the agent’s session changes campaigns. Agents shouldn’t have to hunt for this.

Condensed disposition grid

Rather than one long list shared across all campaigns, disposition codes are scoped and grouped per campaign, cutting the number of clicks between call end and correct wrap-up.

Live status indicators

Pause reason, talk time, and queue position are surfaced prominently rather than buried in a sidebar, which helps both the agent and any supervisor glancing at a shared monitor.

Faster screen-pop integration

When a theme is paired with CRM or lead data integration, the pop should load in the same visual space every time, regardless of which campaign triggered it, so agents build muscle memory across campaigns instead of relearning the layout each time.

Responsive layout 

Multi-monitor agent desks are common on BPO floors, and a theme should behave consistently whether it’s rendered on a single laptop screen or spread across a wider dual-monitor setup.

None of this changes what VICIdial does. It changes how fast an agent can act on what VICIdial tells them.

How a custom theme is actually built

A theme build for an existing VICIdial deployment starts with two pieces of version information: the ViciBox build in use and the SVN (VICIdial codebase) revision the server is running. Themes are built against a specific combination of these, because the underlying template structure and available hooks differ across versions. Skipping this step is the most common reason a theme looks broken after installation on a server it wasn’t built for.

Once versions are confirmed, development typically follows this order:

1. Audit the existing campaign structure and agent workflow to identify where clicks and screen time are wasted.
2. Design the layout, usually as a set of themed variants an operations team can preview and choose between.
3. Build the front end. Current builds favor React for interface logic and Tailwind CSS for styling, layered on top of the existing VICIdial agent session and authentication flow rather than replacing it.
4. Test against live campaign data on a non-production instance.
5. Package the theme for handover, either as source code with installation steps, or installed directly if server access is provided.

After installation, the admin panel path on a themed deployment usually differs from the stock location. A standard build serves the admin dashboard at:

http://[YOUR_SERVER_IP]/vicidial/admin.php

http://[YOUR_SERVER_IP]/vicidial/admin.php

A custom-themed deployment commonly serves it from a client-specific path instead, such as:

https://[YOUR_DOMAIN]/dialer/admin.php

https://[YOUR_DOMAIN]/dialer/admin.php

The authentication mechanism underneath is identical in both cases. Only the file path and the front-end rendering change, which is worth confirming with whoever manages the deployment before assuming a login page has moved for any other reason.

Previewing themes before committing to one

Most VICIdial theme providers, including KingAsterisk, run a public demo portal so operations teams can test a layout before it goes anywhere near a production floor. The general flow looks like this:

Visit the provider’s site and locate the live demo section. Select any available theme option from the list, log in with the demo credentials supplied on the page, and explore the admin dashboard as it would appear post-installation, covering campaign management, agent administration, lead and list handling, inbound and outbound routing, real-time reporting, and recording settings.

This step matters more than it looks. A theme that reads well in a screenshot can still feel cramped on an actual multi-campaign floor once real disposition lists and live agent counts are loaded in.

Diagnosing agent workspace problems: a technical walkthrough

Theme complaints and dialer complaints get reported to support desks in nearly identical language. “The agent screen isn’t working right” could mean the interface, the campaign configuration, or the dialer engine itself. Separating these before touching any front-end code saves hours of misdirected troubleshooting.

Start at the database level. A quick check on live agent state:

SELECT user,status,campaign_id 
FROM vicidial_live_agents;

SELECT user,status,campaign_id 
FROM vicidial_live_agents;

Returns something like:

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

If an agent reports the screen as frozen or unresponsive but their live status shows PAUSED, the issue may sit in session state rather than the theme rendering. This single query rules out half of the usual guesswork.

Manual dialing not working

A more specific case worth walking through: an agent logs in successfully, the theme renders the Dial Next Number button correctly, the agent clicks it, and nothing happens. No outbound call, no screen update, no Asterisk originate action, no visible VICIdial response at all.

Before assuming a theme rendering fault, check the campaign configuration:

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

An auto_dial_level of 0 on a campaign set to manual dialing is a common root cause here, not a front-end defect. The button click event is firing correctly through the theme; the dialer simply isn’t set to act on it. This is exactly the kind of issue a theme audit needs to rule out early, because rebuilding or restyling a button that was never the actual problem wastes development time that should go toward the interface itself.

The broader lesson for multi-campaign floors: any custom theme build should include a short diagnostic pass against agent state tables and campaign dial settings before styling begins, so the finished interface isn’t shipped on top of an unrelated configuration fault.

Non-Agent API and theme integration

Custom themes are frequently paired with lead and reporting integrations that run through VICIdial’s Non-Agent API, a separate interface from the live agent session itself. The Non-Agent API sits at:

http://your-server-ip/vicidial/non_agent_api.php

http://your-server-ip/vicidial/non_agent_api.php

It handles the administrative layer around a theme rather than live call control: injecting new lead lists, updating prospect records from an external CRM, pulling list tallies and campaign metrics, and adding leads directly into the active hopper without a supervisor opening the GUI. Themed dashboards that surface real-time metrics on the agent or supervisor screen are typically drawing from this endpoint in the background.

Live call control from inside an active agent session runs through a separate endpoint, agc/api.php, and is a distinct integration from theme styling itself.

Where to source a custom VICIdial theme

Searches for a custom VICIdial theme download or a custom VICIdial theme free tend to turn up two categories of result. The first is community-shared templates, sometimes distributed through a custom VICIdial theme GitHub repository, which can work as a starting point for a single-campaign setup but generally lack the campaign-aware logic multi-campaign floors need without further development. 

The second is a purpose-built theme developed against your specific ViciBox and SVN version, which costs more upfront but is built around your actual campaign structure rather than a generic layout.

For BPOs running several concurrent campaigns, a generic download rarely holds up once real disposition lists, live agent counts, and screen-pop integrations are layered on top of it. Version mismatches between a downloaded theme and your server’s SVN revision are the most common cause of a theme that installs but renders incorrectly, so confirming compatibility before deployment saves a second round of fixes.

Server requirements for deployment

Theme installation and any accompanying customization work runs on infrastructure the operations team already controls. An AlmaLinux server with a dedicated IP is typically required from the client side for setup, along with server access during installation. Hardware sizing, whether on Intel or AMD builds, is generally recommended based on agent count and campaign volume rather than a fixed specification, so this is worth confirming with whoever handles the deployment before finalizing a theme build.

Frequently Asked Questions

Get a theme built for your campaign structure

KingAsterisk builds custom VICIdial themes against your specific ViciBox and SVN version, starting with a workspace audit rather than a template. Share your current setup details and campaign count, and the team will scope a layout, timeline, and cost estimate suited to a multi-campaign floor.

VICIdial Administration is the set of controls an operator uses to manage users, campaigns, lists, and dialer behaviour from the admin panel. For businesses running outbound or inbound contact operations in Australia, getting this layer right determines whether agents can log in reliably, whether leads reach the right queue, and whether the VICIdial dialer paces calls the way the campaign manager intended.

Unlike a single settings page, VICIdial Administration is distributed across several interlinked modules: Admin, User Groups, Campaigns, Lists, Inbound Groups, and Server settings. Each module writes to specific MySQL tables (vicidial_users, vicidial_campaigns, vicidial_lists, vicidial_user_groups) and those tables are what the dialer engine reads from in real time. This article breaks down the controls that matter most for day-to-day administration and walks through a genuine troubleshooting case involving manual dialing.

Accessing the VICIdial admin panel

On a standard installation, the administrator dashboard sits at:

http://[YOUR_SERVER_IP]/vicidial/admin.php

http://[YOUR_SERVER_IP]/vicidial/admin.php

Default credentials are publicly documented in the open source project, which makes them the single highest-risk item in a fresh deployment. Change both the username and password immediately through Admin, then Users, then Edit User.

Agents log in through a separate interface, typically:

http://[YOUR_SERVER_IP]/vicidial/vicidial.php 

http://[YOUR_SERVER_IP]/vicidial/vicidial.php 

On custom theme deployments built by KingAsterisk, the agent path is often reorganised to something like /agent/agent.php, and the admin path to /dialer/admin.php, depending on the client’s preferred folder structure. The authentication mechanism underneath does not change; only the file path and the visual theme differ. 

If you are working from a KingAsterisk demo build, the sequence is straightforward: open the KingAsterisk website, go to the Live Demo section, choose a theme, and use the Admin button to reach the login page for that theme (for example, a Theme 5 build would expose an admin login at a path like /theme-5/dialer/admin.php).

User Levels, User Groups, and permissions

VICIdial Administration does not use a simple admin-or-agent binary. Access is built from three layers that combine to define what a person can see and do:

User Level is a numeric value, generally from 1 to 9, where higher numbers unlock broader administrative functions. Levels 7 and 8 are commonly used for report-focused staff who need visibility without configuration rights, while full administrative functions typically sit at higher levels.

User Group determines which campaigns, lists, and reports a user can even see as options, separate from what their User Level permits them to do.

Allowed Reports and individual permission flags (View Reports, Modify Users, Modify Campaigns, Modify Lists, Delete Users, Load Leads, and similar) are set per user or per group and override the broader defaults.

A common real-world requirement is limiting a manager to a single report, such as the Agent Time Detail Report, without granting any configuration access. In VICIdial this is handled as follows:

• Create a dedicated User Group under Admin, then User Groups (for example REPORT_USERS).
• In that group’s settings, open Allowed Reports and select only Agent Time Detail Report, deselecting everything else.
• Create the user under Admin, then Users, then Add User, assign them to REPORT_USERS, and set an appropriate User Level (7 or 8 is typical for report-only access).
• In the user’s individual settings, set View Reports to 1 and set every other admin permission, including Modify Users, Modify Campaigns, Modify Lists, Delete Users, and Load Leads, to 0.
• If several managers should each see only their own team’s data, configure Allowed User Groups within the group settings so REPORT_USERS can only pull statistics from the groups you specify.

This combination of User Level plus Allowed Reports plus Allowed User Groups is the standard pattern for granular access control in VICIdial, and it applies whether you’re restricting reporting, list access, or campaign visibility.

The underlying data lines up with the platform’s own permission model. A permissions lookup for a given user typically returns a structure similar to this:

{
  "userId": "agent001",
  "userLevel": 8,
  "permissions": {
    "modifyLeads": true,
    "deleteLeads": false,
    "downloadRecordings": true,
    "viewReports": true,
    "manageCampaigns": false,
    "manageUsers": false
  }
}

{
  "userId": "agent001",
  "userLevel": 8,
  "permissions": {
    "modifyLeads": true,
    "deleteLeads": false,
    "downloadRecordings": true,
    "viewReports": true,
    "manageCampaigns": false,
    "manageUsers": false
  }
}

That data is derived directly from the vicidial_users table (user, user_level) and vicidial_user_groups, which is exactly why User Level and User Group are the two fields administrators should check first whenever a user reports they can or cannot see something they shouldn’t.

Roles as a shortcut, not a replacement

Larger deployments sometimes layer named roles, such as Administrator, Supervisor, or Agent, on top of the User Level and User Group structure to make onboarding faster. A role like Supervisor typically maps to a bundle of permissions such as viewing reports, downloading recordings, live monitoring, and managing callbacks, while an Agent role maps to a narrower set: making calls, updating dispositions, and viewing their own callbacks only. 

Roles are a convenience layer. Underneath, VICIdial still resolves everything back to User Level and User Group, so when a permission dispute comes up, checking those two fields directly is faster than trying to trace it through a role label.

Campaign configuration: the second pillar of administration

Once user access is sorted, campaign configuration is where dialer behaviour actually lives. Each campaign carries settings such as:

• Dial method (RATIO, ADAPT_HARD_LIMIT, ADAPT_TAPERED, or manual)
• Auto dial level, which determines how many lines the system dials per available agent
• Available agent-only override, campaign call times, and dial statuses
• Hopper and lead-loading behaviour for the assigned lists

These fields sit in vicidial_campaigns and are read by the dialer engine on every dial cycle. A misconfigured value here does not throw an error message. It simply changes, or stops, dialer behaviour silently, which is why campaign configuration review is one of the first steps in any dialing issue.

Case study: manual dialing not working

A recurring, genuinely frustrating scenario for administrators looks like this. An agent logs in successfully, is assigned to a campaign, and sees the Dial Next Number button. They click it. Nothing happens: no outbound call, no screen update, no origination on the Asterisk side, no action logged anywhere in VICIdial.

Because the agent can log in and the interface loads normally, it is tempting to suspect a network or telephony fault. In practice, this symptom sets points almost every time at campaign configuration rather than infrastructure.

Start by checking the agent’s live state directly against the database:

SELECT user, status, campaign_id
FROM vicidial_live_agents;

SELECT user, status, campaign_id
FROM vicidial_live_agents;

A result such as:

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

immediately tells you the agent session is registered but paused, which will block manual dialing regardless of what the button appears to do on screen. If status shows as available rather than paused, the next place to look is the campaign record itself. Pull the campaign’s dial settings and check the auto dial level field:

auto_dial_level=0

auto_dial_level=0

An auto dial level of zero effectively tells the dialer not to place any lines for that campaign, including lines initiated manually by an agent pressing Dial Next Number in some configurations, particularly where the campaign is set to a dial method that depends on that ratio for line allocation. 

This single field is one of the most common root causes of a “the button does nothing” report, and it is invisible from the agent’s screen because there is no error state to display. There is simply no instruction reaching the originate layer.

A practical diagnostic order for this exact symptom set looks like this:

• Confirm the agent’s live status in vicidial_live_agents is not PAUSED or in a wait state.
• Confirm the campaign’s dial method matches what the button is meant to do (manual dialing needs the campaign correctly set for it).
• Check auto_dial_level on the campaign record and correct it if it has been zeroed out during a configuration change.
• Confirm the lead the agent is trying to dial has not exceeded its call count or fallen outside the campaign’s local call time window.
• Only after ruling out the above should you look at the Asterisk origination layer itself, since the database and campaign configuration account for the overwhelming majority of manual dial failures.

This is a good general lesson for VICIdial Administration: most dialer symptoms that look like a technical fault are actually a configuration value read directly from the database. Knowing which two or three tables and fields to check first saves hours compared to working backwards from the telephony layer.

Transfers and live call administration

Administration also extends to how agents handle live calls once dialing is working correctly. VICIdial supports two transfer types that administrators should train supervisors on:

Blind transfer sends the call immediately to another agent or department without a conversation first, and is used when there’s no need to brief the receiving party.

Attended, or warm, transfer lets the initiating agent speak with the receiving party before connecting the customer, and is the right choice when context needs to be handed over before the customer joins.

Neither transfer type requires special admin configuration beyond ensuring the destination extension or campaign is reachable and the agent’s permission set allows transfers, which again traces back to their User Level and User Group.

Server and environment requirements

Administrators planning a fresh deployment or a custom theme build should have a few environment details ready before configuration begins. KingAsterisk typically requests the ViciBox version and the SVN codebase version currently in use, since theme and customisation work is built against the existing environment rather than a generic base. 

Hardware is scoped to the expected agent count and campaign volume, with both Intel and AMD options supported. One requirement worth flagging early: an AlmaLinux server with a dedicated IP is needed from the client side before installation and configuration work can begin.

Where custom administration panels fit in

Standard VICIdial administration is fully functional out of the box, but many Australian operators running larger or multi-brand campaigns move to a customised panel for a cleaner interface without losing any underlying control. KingAsterisk builds these on modern front-end stacks, including React-based interfaces and Tailwind CSS styling, while keeping every core administrative function, campaign management, user and agent administration, list management, inbound and outbound routing, real-time reporting, carrier and trunk configuration, call recording settings, and system monitoring, fully intact underneath. 

The admin file path typically moves from /vicidial/admin.php to something like /dialer/admin.php on a custom build, but the permission model, campaign fields, and database structure described throughout this article remain the same.

Frequently Asked Questions

Get administration set up correctly the first time

Misconfigured user permissions and campaign settings are behind most of the dialer issues Australian contact operations run into after go-live. KingAsterisk sets up VICIdial administration correctly from the start, builds custom admin panels where a standard interface doesn’t fit the operation, and troubleshoots existing deployments down to the exact table and field causing the problem. 

Reach out to KingAsterisk to review your current VICIdial administration setup or plan a new deployment.

The VICIdial Webphone removes the  second application entirely. Most VICIdial deployment services in Australia still ask agents to run a desktop softphone alongside the agent screen. Two applications, two login states, two points of failure, and a support queue full of tickets that begin with “my phone disconnected but the dialler says I’m live”. 

The agent opens a browser tab, logs in, and the audio path is established by the same page that renders the lead record.

This guide covers what actually happens underneath that tab, how to configure it correctly on a production system, and how to diagnose the three failure patterns that account for most webphone tickets we see at KingAsterisk.

What the VICIdial Webphone actually is

The term covers a browser-embedded SIP user agent written in JavaScript, typically built on SIP.js or JsSIP, delivered inside an iframe or a panel within the agent interface. It performs the same functions a hardware IP phone or MicroSIP client would perform: it registers an extension, answers an inbound leg from Asterisk, and passes media.

What changes is the transport. A desktop softphone speaks SIP over UDP or TCP and carries audio as RTP. A browser cannot open raw UDP sockets, so the VICIdial Webphone speaks SIP over WebSocket and carries audio as SRTP with keys negotiated through DTLS. Asterisk handles both sides through res_http_websocket and the transport-wss configuration in PJSIP.

For the agent, the practical effect is that the phone login field in the VICIdial agent screen and the audio device become the same session. There is no separate registration to babysit.

How the browser reaches Asterisk

The call path for a webphone agent in an outbound campaign looks like this:

• The agent loads the agent interface over HTTPS. The webphone panel initialises and reads its extension and password from the user record.
• The JavaScript user agent opens a WSS connection to the Asterisk server, normally wss://your-domain:8089/ws.
• A SIP REGISTER is sent across that WebSocket. Asterisk creates or updates the contact for that endpoint.
• VICIdial’s dialler originates a call through AMI. Asterisk places a leg to the registered WebRTC endpoint.
• The browser answers, ICE candidates are exchanged, DTLS completes, and SRTP flows between the browser and Asterisk.

Every one of those five steps can fail independently, which is why a structured diagnosis matters more than restarting services.

Server-side requirements

The webphone needs the following in place before an agent ever logs in:

• Asterisk compiled with res_srtp, res_crypto, res_http_websocket and OpenSSL support.
• HTTP server enabled in http.conf with TLS bound to 8089 and a certificate chain that the browser trusts.
• A PJSIP transport of type wss, and endpoints configured with webrtc=yes, media_encryption=dtls, ice_support=yes, use_avpf=yes, and dtls_verify=fingerprint.
• An RTP port range opened in the firewall, commonly 10000 to 20000 UDP, matching rtp.conf.
• A STUN server entry where agents sit behind NAT.

On the platform side, we recommend AlmaLinux with a dedicated IP address supplied from the client end. Hardware is sized to the agent count and concurrency target, with both Intel and AMD options available, and KingAsterisk handles installation and configuration on the prepared server.

VICIdial-side configuration

Inside the dialler itself, three records matter.

The phones table entry defines the extension the browser registers as, its password, the server IP it belongs to, and the protocol. For a WebRTC endpoint this must be marked as a webphone entry rather than a standard SIP device, or Asterisk will build the dial string without the WebRTC media flags.

The user record carries the webphone URL and the phone login the agent inherits at session start. Where a client runs a custom interface, the path differs from stock. 

A standard build serves the agent screen at http://[YOUR_SERVER_IP]/vicidial/vicidial.php, while a KingAsterisk custom deployment commonly serves it at /agent/agent.php or a client-specified path. Authentication logic is identical; only the file path changes.

The campaign record controls whether the webphone is used for the agent’s session and whether the browser tab is the audio endpoint for auto-dialled calls.

Verifying registration before blaming the browser

Once an agent logs in, confirm the endpoint is genuinely registered rather than assuming the green indicator in the UI is authoritative.

From the Asterisk CLI:

pjsip show endpoints
pjsip show contacts

pjsip show endpoints
pjsip show contacts

Programmatically, the SIP Device Status API returns the same information in JSON, which is useful for monitoring dashboards and supervisor panels:

GET /api/v1/sip/devices?status=ONLINE

A typical response entry:

{
  "extension": "8601",
  "protocol": "PJSIP",
  "deviceName": "Agent 8601",
  "registrationStatus": "ONLINE",
  "ipAddress": "192.168.1.55",
  "lastSeen": "2026-07-15T15:18:40Z"
}

{
  "extension": "8601",
  "protocol": "PJSIP",
  "deviceName": "Agent 8601",
  "registrationStatus": "ONLINE",
  "ipAddress": "192.168.1.55",
  "lastSeen": "2026-07-15T15:18:40Z"
}

Registration status here is read live from Asterisk rather than from a stored configuration value, so a device that appears in the database but not in this response has never completed a WebSocket handshake.

Three failure patterns and how to work through them

1. The webphone registers but the agent never receives a call

Start with the agent state, not with telephony. Run:

SELECT user, status, campaign_id
FROM vicidial_live_agents;

A result such as:

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

tells you the dialler will not route anything to that agent. A paused agent is excluded from the ready pool, so no auto-dialed call and no hopper lead will reach the browser regardless of how healthy the WebRTC session is. If the agent reports they clicked Resume, check whether the pause code selection completed and whether the session is writing updates at all. A stale row with an old last_update_time points to a browser tab that lost its keepalive rather than to a paused agent.

2. Auto-dialling produces nothing

Check the campaign:

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

With auto_dial_level set to zero, the dialler places no automatic outbound attempts. The campaign is in manual mode by design. Agents in that campaign must originate calls themselves, and the webphone will sit silent and idle while appearing perfectly healthy. Before changing the value, confirm the campaign was intended to run predictive or ratio dialling. Raising the level on a campaign built for manual verification work will generate abandoned calls and compliance exposure.

3. Manual dialling does not work

This is the pattern that costs the most support time, because everything looks correct.

Symptoms: the agent logs in successfully. The webphone registers. The agent sees the Dial Next Number button and can click it. Nothing happens. There is no outbound call, no screen update, no Asterisk originate, and no VICIdial action recorded.

Work through it in this order:

• Confirm the agent session is writing to the database. If vicidial_live_agents shows no recent update for that user, the browser is not completing its polling cycles. 
• Check for a blocked request in the browser console, a reverse proxy stripping requests, or mixed-content blocking where the agent page is HTTPS but an internal request is HTTP.
• Confirm the campaign permits manual dialling and that the agent’s permissions include it. The Agent Skills API exposes this directly:

GET /api/v1/agents/{agentId}/skills

GET /api/v1/agents/{agentId}/skills

A permissions array containing ManualDial confirms the entitlement exists.

• Confirm the hopper has leads available for the list the campaign is using. Dial Next Number pulls from the hopper; an empty hopper produces exactly this silence.
• Watch Asterisk during the click. If no origin appears in the manager log, the failure is between browser and database. If an origin appears and fails, the problem is the carrier or dial plan, not the webphone.
• Confirm the dial prefix, the campaign’s dial timeout, and the outbound caller ID are valid for Australian numbering. A malformed prefix on a 61-prefixed number can cause an origin to be rejected before it reaches the carrier.

To test the telephony path independently of the agent screen, originate a call through the API and observe whether the browser rings:

POST /api/v1/calls/originate
{
  "agentId": "agent001",
  "campaignId": "OUTBOUND001",
  "phoneNumber": "+61280001234",
  "recording": true
}

POST /api/v1/calls/originate
{
  "agentId": "agent001",
  "campaignId": "OUTBOUND001",
  "phoneNumber": "+61280001234",
  "recording": true
}

A 202 response with CALL_INITIATED and a silent browser isolates the fault to the WebRTC leg. No response at all isolates it to AMI or campaign configuration.

One-way audio and other media faults

When signalling succeeds but audio does not, the cause sits in media handling.

Silence in both directions after an answer usually means DTLS never completed. Check the certificate on port 8089, its expiry, and whether the chain is complete. Browsers will establish the WebSocket against a trusted certificate and still fail the DTLS handshake if the fingerprint verification setting is inconsistent.

Audio in one direction only points to RTP reaching the browser but not returning, or the reverse. Verify the RTP port range is open bidirectionally, that ice_support is enabled, and that a STUN server is reachable from agent networks. Corporate networks in Australia frequently block high UDP ranges by default.

Choppy audio with good signalling is jitter. For distributed teams across Sydney, Melbourne, Brisbane, Perth and Adelaide, server placement matters. A server located near the majority of agents reduces round-trip delay measurably, and carrier health should be validated alongside it:

GET /api/v1/carriers/status

GET /api/v1/carriers/status

ASR and ACD figures returned there give a fast read on whether degradation is local media or upstream carrier behaviour.

Microphone permission and browser behaviour

The webphone calls getUserMedia to capture audio. Browsers grant that only on secure origins, and only after explicit user consent. Two consequences follow.

First, the agent interface must be served over HTTPS with a trusted certificate. An IP-address URL with a self-signed certificate will load the page and fail the microphone request.

Second, a permission denied once may be remembered by the browser profile. An agent who clicked Block on their first day will keep failing until the site permission is reset, even after a full system restart. Include that check in your first-line script.

Where the webphone fits in a wider deployment

Browser-based calling changes what else becomes possible. With no desktop client to install, agent onboarding for a distributed Australian team reduces to a URL and credentials. Screen pops, click-to-dial from a CRM record, and supervisor monitoring all operate against the same session. 

KingAsterisk builds WebRTC softphones, custom agent interfaces, CRM integrations with Salesforce, HubSpot, Zoho and custom platforms, multi-level IVR flows, AMI-driven live dashboards, and performance tuning for high-concurrency MariaDB environments.

People also ask

Talk to KingAsterisk

If your agents are still running a separate softphone, or your existing webphone drops registrations under load, KingAsterisk can audit the deployment and implement a browser calling setup built for your environment. We handle Asterisk and PJSIP configuration, certificate and transport setup, custom agent interface development, CRM integration, and ongoing support for Australian operations.

Contact KingAsterisk to discuss your requirements and get a deployment plan for your server.

Most teams building against VICIdial run into the same wall early on. The VICIdial API documentation is scattered across an aging wiki, a Subversion repository, and forum threads that are ten years old in places. There is no single, current reference that lays out every endpoint, every parameter, and every failure mode in one place.

This guide is written for developers, integration engineers, and technical leads across Australia who are connecting a contact platform to a CRM, a lead system, or an internal dashboard, and who need working detail rather than a marketing overview. 

It covers the two native interfaces VICIdial ships with, how a REST layer is typically built on top of them, where to find source material, and a real diagnostic case involving a stalled manual dial function.

What VICIdial API documentation actually covers

When people search for VICIdial API documentation, they are usually looking for one of three things: how to pull or push data programmatically, how to control an agent’s live session from an outside application, or how to build a REST layer over the platform for a CRM or reporting tool. 

VICIdial itself does not ship a formal OpenAPI specification. What it provides instead are two PHP-based interfaces that have existed since the early Asterisk-based dialer builds, plus a database schema that experienced integrators query directly for read-heavy reporting needs.

Because the native interfaces are parameter-driven HTTP scripts rather than a documented REST contract, most integration partners, including KingAsterisk, build a REST specification layer on top of them. That layer maps familiar HTTP verbs and JSON payloads onto VICIdial’s underlying tables and scripts, which is what makes modern CRM and lead-management connections practical.

The two native VICIdial APIs

VICIdial’s own interfaces split cleanly by what they are allowed to touch.

VICIdial Agent API

The Agent API is used once an agent is already logged into their web session. It lets an outside application drive that session: pausing the agent, resuming them, initiating a click-to-call, applying a disposition, or transferring a live call. Because it depends on an authenticated, in-progress session, it is the interface behind click-to-call buttons embedded in a CRM record and behind supervisor tools that need to nudge a specific agent’s screen state.

A REST wrapper built over this interface typically exposes a live agent status endpoint and an agent login status endpoint, since most external systems need to know whether an agent is online before attempting any session-level action. A login status check, for example, returns a simple structure confirming whether the agent is currently logged in, what time they logged in, which server they are attached to, and which campaign they are working:

{
  "success": true,
  "data": {
    "loggedIn": true,
    "loginTime": "2026-07-15T08:01:10Z",
    "serverIp": "192.168.10.15",
    "campaignId": "OUTBOUND001"
  }
}

{
  "success": true,
  "data": {
    "loggedIn": true,
    "loginTime": "2026-07-15T08:01:10Z",
    "serverIp": "192.168.10.15",
    "campaignId": "OUTBOUND001"
  }
}

A parallel live status endpoint returns the same detail for every agent on a campaign at once, including pause codes and the customer number currently connected, pulled from the vicidial_live_agents table. That table is the single most useful reference point for anyone debugging agent-state issues, a point worth remembering before the troubleshooting section below.

VICIdial Non-Agent API

The Non-Agent API is the interface most integration work actually runs through, because it does not require a live agent session at all. It is the backend workhorse for:

• Lead generation and data processing: injecting new lists, inserting individual prospects, updating contact details, or removing leads from an external CRM
• Data retrieval and reporting: pulling lead status history, checking list tallies, and downloading campaign metrics without a human opening the administration screen
• Campaign and system administration: adding users, adjusting campaign profiles, or pushing a high-priority lead straight into the active dialing hopper

Because the Non-Agent API operates outside any single agent’s session, it is the correct choice for CRM synchronisation, batch lead uploads, and scheduled reporting jobs. The VICIdial Agent API should only be reached for when the task genuinely depends on a live, logged-in agent screen, such as click-to-call or pause and resume control.

Building a REST layer: a documentation example

Most developers searching for a VICIdial API documentation example are not looking for the raw PHP scripts; they are looking for how a modern JSON contract gets built on top of them. A typical specification follows REST conventions closely: HTTPS only, TLS 1.2 or above, JSON with UTF-8 encoding, ISO 8601 timestamps, and E.164 phone number formatting.

Authentication runs on a Bearer token passed in the request header:

Authorization: Bearer eyJhbGc.....

Authorization: Bearer eyJhbGc.....

An unauthenticated request returns a standard structure:

{
  "success": false,
  "code": 401,
  "message": "Unauthorized Access"
}

{
  "success": false,
  "code": 401,
  "message": "Unauthorized Access"
}

Endpoints are grouped by function rather than by which native script they eventually call. A lead management group typically covers import, lookup, update, status lookup, and bulk update. A campaign group covers listing, configuration, and statistics. An agent group covers listing, live status, performance, login status, and skills. A call management group covers history, live calls, recording metadata, and disposition and notes.

This grouping matters for anyone planning an integration, because it separates what the platform can answer instantly, a live agent status query for instance, from what requires a reporting pass across historical tables, such as a campaign statistics query spanning a date range. Building rate-limit and caching decisions around that distinction saves a lot of rework later.

Manual dialing not working: a real diagnostic walkthrough

One of the most common support tickets tied to API-connected deployments has nothing to do with the API layer at all. It looks like this:

Symptoms

The agent logs in successfully. The agent sees the Dial Next Number button and can click it. Nothing happens afterwards: no outbound call, no screen update, no Asterisk originate event, no VICIdial action of any kind. Manual dialing should work. It does not.

First diagnostic step

Before touching Asterisk logs or the dialer process itself, check the agent’s live state directly against the database:

SELECT user, status, campaign_id
FROM vicidial_live_agents;
In one recent case this returned:
TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

SELECT user, status, campaign_id
FROM vicidial_live_agents;
In one recent case this returned:
TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

An agent sitting in a PAUSED state will show the interface and respond to button clicks, but VICIdial will not action a dial request until the status changes to READY. This single line is often the entire answer, and it is why the live agent status query belongs at the top of any manual dial investigation rather than at the bottom.

Second diagnostic step

If the agent status checks out as READY and the button still does nothing, the next place to look is the campaign’s dial level configuration:

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

An auto_dial_level of 0 disables automatic and manual dialing outbound for that campaign entirely, regardless of agent state. This setting is frequently left at zero on a newly built or newly cloned campaign, and it produces exactly the symptom described above: a responsive interface with no downstream action, because the campaign itself is configured to originate nothing.

Resolution path

1. Confirm agent status is READY, not PAUSED, using the live agent query above.
2. Confirm the campaign’s auto_dial_level is set above zero for manual dial to function.
3. If both check out, review the Asterisk manager connection for the server the agent is attached to, since a dropped AMI connection produces the same symptom set with a correctly configured campaign.
4. Recheck the agent’s permission set through the skills endpoint if using a REST layer, since a ManualDial permission omission on the agent record will silently block the action even when the campaign and status are both correct.

This kind of layered check, database state, campaign configuration, then transport layer, is the same order worth following for most VICIdial API integration faults, because the symptom visible to the agent or to the external application is almost always several steps removed from the actual cause.

Server requirements for API-connected deployments

Any deployment that will run a REST layer alongside VICIdial needs a server environment sized to the expected concurrency rather than the agent headcount alone. KingAsterisk suggests hardware based on the specific requirements of each build, with support available across multiple Intel and AMD configurations and compatibility across a range of server environments. For custom panel and theme work specifically, an AlmaLinux server with a dedicated IP address is required from the client side, along with server access for installation.

Why this matters for VICIdial API integration projects

A VICIdial API integration project succeeds or fails on how clearly the two native interfaces are separated in the design. Treating the Agent API and Non-Agent API as interchangeable, or routing bulk lead operations through an agent-session-dependent call, is the most common design mistake in early integration work. 

Once that separation is respected, and a REST specification is built to map cleanly onto it, most CRM, reporting, and lead-management connections become straightforward to build and to maintain.

KingAsterisk builds these specifications directly from client environments rather than from generic templates, covering lead management, campaign and list operations, agent and call reporting, and real-time telephony actions such as originate, transfer, and hold, mapped against the exact database tables and scripts a given deployment runs on.

Frequently Asked Questions

Get a VICIdial API specification built for your environment

If your team is planning a CRM connection, a lead-management build, or a reporting layer against VICIdial, KingAsterisk develops the specification directly from your ViciBox version, SVN codebase, and existing campaign structure. 

We will then map it against the Agent and Non-Agent interfaces your deployment actually runs. Reach out to KingAsterisk to scope the endpoints your integration needs. 

VICIdial agent login is not just a form – it is a database write, a session handshake with Asterisk, and a permission check that decides what that agent is allowed to do for the rest of their shift. Every VICIdial dialer session starts with one action: an agent typing a user ID, a password, and a campaign into a login screen. 

For a supervisor troubleshooting a stalled shift, or a developer wiring VICIdial into a CRM, that single action is where most operational problems either begin or end. 

For contact center teams in Australia managing distributed agents across time zones, the login step also carries practical weight: shift handovers, remote agent connectivity, and integration with rostering or CRM systems all depend on knowing exactly what happens when someone logs in – and what to check when they cannot. 

This guide breaks down the VICIdial agent login process end to end: the URL structure, the password model, the newer agent web client, the login API, and a real troubleshooting case where login succeeds but dialing does not.

What actually happens when an agent logs into VICIdial

The VICIdial agent login screen asks for three pieces of information: a user ID, a password, and a campaign ID. A fourth field, the phone login, ties the browser session to a specific SIP extension or softphone registration. When an agent submits this form, VICIdial does not simply grant access to a page – it performs a sequence of checks and writes that determine everything about the session that follows.

First, the submitted credentials are checked against the vicidial_users table. If the user ID and password match an active record, VICIdial confirms the agent’s user level and user group, which together determine what buttons, campaigns, and reports that agent can see. Next, VICIdial checks that the requested campaign is active and that the agent’s user group is permitted to work it – an agent cannot simply type any campaign ID into the login screen and expect access.

Once both checks pass, VICIdial inserts a row into vicidial_live_agents, recording the agent’s username, campaign, extension, and an initial status. This table is the single source of truth for “who is logged in right now” across the entire installation, and it is what every supervisor screen, wallboard, and reporting query reads from. The phones table is checked in parallel to confirm the extension is registered with Asterisk before the agent is marked ready to take or place calls.

The VICIdial agent login URL structure

On a standard installation, the agent interface is reached at:

http://[YOUR_SERVER_IP]/vicidial/vicidial.php 

http://[YOUR_SERVER_IP]/vicidial/vicidial.php 

This is separate and distinct from the administration login, which lives at /vicidial/admin.php. Custom theme deployments often move the agent interface to a different path – KingAsterisk’s custom builds, for example, commonly serve it at /agent/agent.php or a client-specified path. The file path changes; the underlying authentication logic against vicidial_users does not.

Agent web client 2.0 login

Agent web client 2.0 refers to the newer interface layer used on more recent VICIdial builds and on most custom theme deployments, including KingAsterisk’s React-based agent interfaces. The visual layout changes – real-time status updates arrive over a persistent connection rather than a page refresh, and the screen is generally built to work better on narrower displays for agents working from a laptop rather than a fixed workstation. 

What does not change is the authentication step underneath it: agent web client 2.0 still checks the same vicidial_users credentials and still writes to vicidial_live_agents on a successful login. Teams evaluating an upgrade to the newer client should treat it as an interface and transport change, not a change to how accounts, passwords, or permissions are managed.

VICIdial agent login API – programmatic visibility into login state

Integrating VICIdial agent login into a CRM, workforce dashboard, or automation workflow does not mean querying the agent screen or the underlying tables directly. VICIdial exposes two separate API surfaces for exactly this purpose, and choosing the right one matters.

For login state specifically, a REST-style integration layer built on top of these – the kind KingAsterisk implements for CRM and dashboard integrations – typically exposes a dedicated login-status endpoint. A request against /api/v1/agents/{agentId}/login returns a structured response such as:

{
  "success": true,
  "code": 200,
  "data": {
    "loggedIn": true,
    "loginTime": "2026-07-15T08:01:10Z",
    "serverIp": "192.168.10.15",
    "campaignId": "OUTBOUND001"
  }
}

{
  "success": true,
  "code": 200,
  "data": {
    "loggedIn": true,
    "loginTime": "2026-07-15T08:01:10Z",
    "serverIp": "192.168.10.15",
    "campaignId": "OUTBOUND001"
  }
}

This is useful for workforce management tools that need to confirm an agent has actually logged in for a rostered shift without polling the database. A companion endpoint, the live agent status API, returns real-time state across every logged-in agent:

{
  "success": true,
  "code": 200,
  "data": [
    {
      "agentId": "1001",
      "username": "agent001",
      "campaignId": "OUTBOUND001",
      "status": "INCALL",
      "pauseCode": null,
      "loginTime": "2026-07-15T08:00:00Z"
    },
    {
      "agentId": "1002",
      "username": "agent002",
      "campaignId": "OUTBOUND001",
      "status": "PAUSED",
      "pauseCode": "BREAK"
    }
  ]
}

{
  "success": true,
  "code": 200,
  "data": [
    {
      "agentId": "1001",
      "username": "agent001",
      "campaignId": "OUTBOUND001",
      "status": "INCALL",
      "pauseCode": null,
      "loginTime": "2026-07-15T08:00:00Z"
    },
    {
      "agentId": "1002",
      "username": "agent002",
      "campaignId": "OUTBOUND001",
      "status": "PAUSED",
      "pauseCode": "BREAK"
    }
  ]
}

The status field maps directly to values VICIdial writes internally: READY, INCALL, PAUSED, DISPO, WRAPUP, and DEAD (an unexpected logout). Any integration built against this endpoint should treat DEAD as an operational alert rather than a routine state – it usually means the agent’s browser session or extension dropped without a clean logout, which needs a supervisor’s attention. 

All of these API requests carry a bearer token in the Authorization header, and unauthorized calls return a standard 401 response rather than partial data, which matters when the integration is handling account-linked information.

Diagnosing a login that isn’t behaving

When a login-related ticket comes in, the fastest diagnostic step is not the browser – it is the vicidial_live_agents table itself, which reflects exactly what the login process wrote.

SELECT user, status, campaign_id
FROM vicidial_live_agents;

SELECT user, status, campaign_id
FROM vicidial_live_agents;

A result such as:

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN

tells a supervisor something specific: the login itself succeeded. The credential check passed, the campaign check passed, and a row was written. The agent is not stuck at the login screen – they are sitting in a paused state inside a live session, most likely on a break code or waiting on a manual state change. 

This distinction matters operationally, because “the agent can’t log in” and “the agent is logged in but paused” call for completely different fixes. The first points at credentials, campaign permissions, or extension registration. The second points at agent workflow, pause code configuration, or a campaign left in a state the agent doesn’t expect.

When login succeeds but manual dialing does not work

This is one of the more disorienting tickets a supervisor can receive, because every visible signal looks correct: the agent has logged in, the campaign has loaded, and the Dial Next Number button is sitting right there, clickable. And then nothing happens.

Symptoms

• Agent logs in successfully
• Agent sees the Dial Next Number button and can click it
• No outbound call is placed
• No screen update occurs
• No Asterisk originate event fires
• No VICIdial action is logged against the attempt

Where to look first

The most common cause in this exact pattern is a campaign configuration value, not a login or permission problem. Check the campaign’s dial method setting:

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

An auto_dial_level of 0 combined with a campaign set to a mode that expects the dialer engine – rather than manual agent action – to initiate calls will produce exactly this symptom: the button exists on the screen, the click registers in the browser, but the originate request never reaches Asterisk because the campaign is not configured to accept a manual trigger from that agent state. Three places to check in sequence:

1. Campaign dial method. 

Confirm the campaign is genuinely set for manual or click-to-call dialing, not left on an automated mode with a manual-looking interface.

2. Agent permission scope. 

Cross-check the agent’s assigned permissions – the ManualDial permission specifically – against their user group. An account without it will show the button but silently reject the click server-side.

3. Hopper and lead availability. 

If the hopper has no eligible leads loaded for that agent’s filters, there is nothing to dial against regardless of button state, and the failure looks identical from the agent’s side.

Working through these in order – campaign configuration, then permission scope, then lead availability – resolves the large majority of “logged in but can’t dial” tickets without needing to touch Asterisk logs directly.

Admin login vs agent login – two different doors

It’s worth being explicit about this because the two are frequently confused in support conversations. The administration dashboard, reached at /vicidial/admin.php on a standard build (or a custom path such as /dialer/admin.php on a KingAsterisk theme deployment), controls campaigns, user accounts, lists, and system settings. The agent login at /vicidial/vicidial.php (or its custom-theme equivalent) is scoped entirely to that one agent’s session. 

Default administrator credentials are publicly documented across VICIdial installations generally, which makes changing both the username and password immediately after first login – through Admin – Users – Edit User – one of the highest-value security steps in any new deployment.

Where KingAsterisk fits

KingAsterisk builds on top of the standard VICIdial agent login and administration structure rather than replacing it – every custom theme, React-based agent interface, or Tailwind-styled login screen still authenticates against the same vicidial_users table and writes to the same vicidial_live_agents record described above. The work sits in a few specific areas:

• Custom agent interfaces and supervisor dashboards, including agent web client 2.0-style real-time status screens
• Browser-based softphone integration for agents who need a login-to-dial path without a physical handset
• API development connecting login status, campaign data, and lead activity into external CRM and workforce systems
• Security hardening around session handling, credential storage, and administrator access
• Custom reporting on login/logout timing, pause code use, and agent occupancy

For AU-based operations coordinating shifts across a single time zone or a distributed remote team, this typically means a login and permission structure that maps cleanly to rostering, plus API access that lets a workforce tool confirm attendance without a supervisor manually checking the agent screen.

Frequently asked questions

Get your VICIdial agent login environment right

Whether the issue is a custom agent web client rollout, a login API integration into an existing CRM, or a campaign that’s quietly blocking manual dials despite a clean login, KingAsterisk works on the VICIdial deployment layer every day. 

Reach out to talk through your current setup, your ViciBox and SVN versions, and what a login and permission structure built for your team would look like.

The VICIdial Supervisor Analytics Theme is a purpose-built dashboard that gives contact center supervisors a live, consolidated view of every metric that matters – agent states, wait times, call volume, and queue performance – all updated in real time. For operations teams running busy contact centers on VICIdial, the difference between reacting to a problem after the damage is done and catching it while it is still manageable often comes down to what is on the supervisor’s screen. 

This article explains what the theme delivers, how to configure it, and how organisations get the most out of it in daily operations.

The VICIdial admin login screen is the entry point for supervisors and administrators. Access is controlled through VICIdial’s built-in user management, so only authorised personnel reach the analytics dashboard.

What the VICIdial Supervisor Analytics Theme actually does

The standard VICIdial supervisor panel shows data, but its layout was designed around function, not speed of comprehension. A supervisor managing 40 agents across three inbound campaigns has to click through multiple screens to get a complete picture. The analytics theme changes that by pulling all of the same underlying data into a single, high-contrast view that a supervisor can scan in seconds.

The admin dashboard gives a consolidated view of all active campaigns, agent counts, and current queue status. Everything visible here updates without a page refresh, so the data on screen reflects what is happening on the floor right now. 

The theme runs in the browser, reads from the VICIdial real-time reporting tables, and refreshes at configurable intervals – typically every two to five seconds. No separate server process is required. The interface is responsive, which means it can run on a dedicated wall-mounted monitor showing the full floor view, or on a supervisor’s secondary screen.

The outcome is not just cosmetic. When the data is easier to read, supervisors make faster decisions. Agents who are stuck on hold get flagged. Queues that are building get spotted before abandonment rates tick upward.

Core metrics displayed on the dashboard

Real-time reports pull directly from VICIdial’s live data tables. Supervisors can see call volume, wait times, answer rates, and drop rates across all campaigns in a single view — no manual report generation required.

Agent state breakdown

Every logged-in agent appears with their current state: INCALL, CLOSER, DISPO, PAUSED, or DEAD. The colour-coded grid makes it immediately obvious if an unusual number of agents are in pause or dispo simultaneously. Supervisors can also see how long each agent has been in their current state, which flags excessive pause time without needing to pull a separate report.

Live queue and campaign stats

Each active campaign shows the number of calls waiting, the average wait time, the current answer rate, and the number of agents assigned. When a VICIdial inbound queue starts building, the waiting call count turns amber and then red based on configurable thresholds. No manual calculation is needed – the threshold logic is built in.

Call volume and drop rate indicators

The dashboard aggregates the total calls answered, calls dropped, and current average handle time across all active campaigns. Drop rate is particularly valuable for outbound operations: a spike in dropped calls often signals a dial ratio issue before it becomes a compliance concern.

Hourly trend bars

A compact bar view shows call volume and answer rates for each hour of the current shift. This lets supervisors see at a glance whether performance is tracking ahead of or behind the same period on the previous day, without opening a separate reporting module.

How the real-time data feed works

VICIdial stores live operational data in a set of MySQL tables – live_inbound_agents, vicidial_live_agents, vicidial_campaigns, and related tables. The supervisor analytics theme queries these tables directly using AJAX calls that fire on a polling interval set in the theme’s configuration file. The default is three seconds, which is usually the right balance between freshness and server load.

For larger deployments running more than 200 concurrent agents, it is worth increasing the polling interval to five or six seconds and adding a read replica for the reporting queries. This prevents the real-time dashboard from adding load to the same database connection pool that handles dialer operations.

The theme does not require WebSockets, which keeps the setup simple. The data is fetched as JSON and rendered client-side. This means even a basic Apache or Nginx web server can serve the theme without any additional back-end infrastructure.

Setting up and customising the theme

Agents log in through the standard VICIdial agent interface. The supervisor analytics theme runs in parallel, pulling agent state data from VICIdial’s live tables as soon as an agent session is active.

Minimum requirements

The theme runs on any server that already hosts VICIdial. It requires PHP 7.4 or higher, MySQL 5.7 or MariaDB 10.3 or higher, and a web server with mod_rewrite enabled. Browser-side, it works on Chrome, Firefox, and Edge without any plugins.

Installation steps

The theme files sit in a subdirectory of your VICIdial web root, typically /var/www/html/vicidial/supervisor_theme/. The config.php file holds the database credentials, the polling interval, and the campaign filter list. Once configured, the dashboard is accessible at the subdirectory URL and login is handled through VICIdial’s existing session management.

Customisation options

The most commonly adjusted settings are the colour thresholds for queue depth alerts, the list of campaigns displayed, and whether the hourly trend bars show the current day only or a comparison against the prior day. Teams with branded interfaces often update the CSS variables to match their internal tool colour scheme. The theme’s stylesheet uses CSS custom properties throughout, so a brand colour update requires changing fewer than ten lines.

Common mistakes supervisors make without live analytics

The absence of a real-time view leads to a predictable set of problems. Understanding them is useful both for making the case for the theme and for configuring it correctly once deployed.

The agent dashboard shows each agent’s current state, time in state, and campaign assignment in real time. Supervisors can spot excessive pause time or dispo lag immediately, without checking each agent individually.

Relying on scheduled reports creates a lag between the event and the response. A drop in answer rate that shows up in a 30-minute report has already been affecting customers for up to 30 minutes.

Manual agent monitoring – supervisors walking the floor or sending internal messages to check agent status – is inconsistent and does not scale beyond small teams.

Without a queue depth view, supervisors cannot distinguish between a slow period and a period where agents are available but callers are not waiting long enough to be answered. These two situations require opposite responses.

Pause time misuse is difficult to catch without a live agent state view. An agent in PAUSED state for 12 minutes looks exactly the same as one in PAUSED for 90 seconds until someone checks – and without the theme, checking requires opening the supervisor panel manually for each agent.

Frequently asked questions

Conclusion

The VICIdial Supervisor Analytics Theme solves a specific and common problem: supervisors managing busy operations cannot act on information they do not have. Real-time visibility into agent states, queue depth, drop rates, and hourly trends gives supervisors the context to make staffing decisions in the moment rather than after the fact.

The setup is straightforward for any team already running VICIdial. The community version on GitHub is a good starting point for technical teams, while production deployments benefit from a maintained build that tracks VICIdial version changes. The real-world impact – shorter wait times, fewer dropped calls, faster reassignment of idle agents – comes from making the right data easy to read at a glance.

KingAsterisk has deployed and customized the VICIdial Supervisor Analytics Theme for contact centers across India, Southeast Asia, the United States, and the Middle East. If your operation runs VICIdial and you want to implement or tailor this dashboard for your specific setup, contact the KingAsterisk team for a no-obligation conversation about what would work for your environment.

A VICIdial AI call summary layer solves a problem: it takes the recording VICIdial already produces and turns it into a short written recap that sits next to the lead, without changing how agents dial or how campaigns are built.

A supervisor running an outbound campaign with a few hundred leads a day does not have time to sit through every recorded call. Agents move from one conversation to the next, notes get shorter as a shift wears on, and by the time a lead needs a follow-up call, nobody quite remembers what was actually said the first time.

This guide walks through what that setup looks like in practice, how it fits into a VICIdial and Asterisk install, and where it runs into the same kind of configuration and data questions that come up with any custom addition to a dialer.

What is the purpose of VICIdial

VICIdial is an open source contact center platform built on Asterisk. It handles outbound dialing (predictive, progressive, or manual), inbound queues, campaign management, agent screens, and reporting, and it stores everything in a MySQL or MariaDB backend. A campaign like US_SOLAR ties together a lead list, a set of dial rules, and a group of agents; the hopper pulls leads from the list, Asterisk originates the call, and the agent’s screen updates once a call connects.

Because the whole system is open, teams add their own layers on top of it all the time, whether that is a custom lead field, a webhook into a CRM, or, in this case, a summary written back into the lead record after each call ends.

Why call summaries matter as campaigns scale

A single agent handling calls all day generates dozens of recordings. Multiply that across five, ten, or fifty agents, and a supervisor reviewing conversations for quality or compliance is choosing between listening to a small sample and missing everything else, or falling permanently behind. 

A written summary attached to each lead gives a supervisor something they can scan in a few seconds, and it gives the next agent who picks up that lead a starting point instead of a blank slate.

It also helps close the loop on details that live only inside the conversation itself: a customer’s stated preference, an objection raised, or a date they asked to be called back. Right now, that information exists only as audio unless someone writes it down.

How a VICIdial AI call summary pipeline actually works

The pieces already exist in a standard VICIdial and Asterisk install. Adding a summary layer means connecting them rather than replacing them.

Asterisk records the call, typically through MixMonitor, and writes the audio file to the recording path defined in the campaign. VICIdial logs the call metadata separately: lead ID, campaign, start and end time, length in seconds, and the termination reason, in tables such as vicidial_log and vicidial_close_call_log. Neither of those steps needs to change.

What gets added is a small process that watches for newly closed calls, either by polling those log tables on an interval or by triggering off the agent’s disposition event. When a call closes, that process picks up the matching recording file, sends it to a transcription and summarization service, and waits for a short text summary back. 

That summary is then written into a custom lead field, so it shows up on the same lead screen an agent already uses, right next to the phone number and disposition history.

None of this touches the SIP trunk, the PJSIP configuration, or the dial plan. The summary layer sits alongside the call flow and reads from it after the fact, which keeps it low risk to add to a live campaign

Setting up an AI call summary layer on your VICIdial install

A rollout that avoids disrupting live campaigns usually follows this order.

• Confirm the database schema version matches your VICIdial release and that lead import and dialing are both working normally before adding a new dependency on top.
• Add a custom lead field for the summary text so it renders on the standard lead view without a separate screen.
• Build a script that watches vicidial_log or vicidial_close_call_log for calls that have just closed, keyed by lead ID and call date.
• Route the matching recording to a transcription and summarization endpoint of your choice.
• Write the returned summary back to the lead record with a scheduled database update.
• Pilot on a single campaign with a small agent group before turning it on everywhere.

How to monitor calls on VICIdial

VICIdial’s built-in monitoring covers a different need: watching a call as it happens. From the admin or supervisor screen, a manager can listen in on a live agent, whisper coaching to the agent without the customer hearing, or barge in and join the conversation directly. The live agent screen shows each agent’s current status and campaign in real time, which is where a supervisor decides who to monitor next.

A call summary does not replace that. It picks up after the call ends, giving a supervisor a written record to check without needing to have been listening at the time. Teams that use both together tend to reserve live monitoring for coaching in the moment and use summaries for after-the-fact review and lead handoffs.

Is AI calling illegal?

Summarizing a call is not illegal on its own, but it inherits the same rules that already apply to recording the call in the first place. Many places require some form of consent before a conversation is recorded, and that requirement does not disappear because the recording is later summarized rather than played back in full. 

Some jurisdictions require both parties to agree to recording, others only require one party to know, and outbound campaigns calling across state or country lines can be subject to more than one set of rules at once.

A campaign like US_SOLAR calling into the USA, for example, sits under different disclosure requirements than a domestic US campaign would. Before adding any summarization step, it is worth checking recording consent rules for every region a campaign touches, disclosing the recording to customers as required, and confirming with legal counsel how long summaries and recordings can be retained.

What to look for in AI call summary services for virtual receptionists

Virtual receptionist services and stand-alone summarization tools vary quite a bit in how well they actually fit onto an existing dialer. A few things are worth checking before picking one.

• Accuracy on real call audio, including accents, background noise, and crosstalk, not just clean sample recordings.
• A plain API or webhook interface, so it can plug into a script rather than requiring agents to change screens.
• Clear data retention and deletion policies for both the audio and the resulting text.
• Reasonable turnaround time between a call ending and a summary being available.
• Per-minute or per-call pricing that scales sensibly with actual call volume.

Services built specifically for virtual receptionists are often tuned for short, single-topic calls. An outbound sales or collections conversation runs longer and covers more ground, so it is worth testing any service against a handful of real recordings from your own campaigns before committing to it.

Pairing AI Asterisk tooling for a fuller setup

Some teams choose to connect a transcription or summarization tool directly to Asterisk, through AGI or ARI, rather than through VICIdial’s own lead and campaign tables. That approach can make sense for larger, multi-application Asterisk deployments where VICIdial is only one of several things running on top of the same telephony layer. 

For a single-platform VICIdial setup, working through the lead and log tables, as described above, is usually the simpler path and keeps the summary logic close to the campaign data it is meant to support.

Getting a VICIdial sign up going

There is no online sign up form for VICIdial itself, since it is open source software you install on your own server rather than a subscription you activate. Getting started means either building the install yourself, following the standard Debian and Asterisk setup steps, and configuring campaigns and agents from there, or working with a provider who sets up and configures the platform for you as a project. 

Either route ends at the same place: a working VICIdial instance with campaigns, agents, and a database schema you can then extend with additions like an AI call summary layer.

Frequently Asked Questions

Ready to add call summaries to your VICIdial setup

Turning recorded calls into short, useful summaries is one of the more contained additions you can make to a VICIdial install, since it works alongside the existing dialer and database rather than replacing anything. 

If you want help scoping a call summary layer, checking your schema and campaign configuration first, or choosing a summarization service that fits your call volume, KingAsterisk works with VICIdial and Asterisk deployments on exactly this kind of project.

A VICIdial lead import system failure almost always looks the same from the outside: the upload screen confirms the file went through, the list detail page shows no change in lead count, and agents log in to an empty hopper with nothing to dial. For teams running outbound campaigns in Australia and other regions with non-US numbering formats, this is one of the most frequent VICIdial support tickets KingAsterisk receives, and in the overwhelming majority of cases the server is fine. 

The real cause sits inside VICIdial’s lead-load validation logic, which rejects rows before they ever reach the vicidial_list table and reports the rejection as a BAD-PHONE error.

This guide walks through reproducing the failure step by step, reading the validation output correctly, fixing the phone number formatting and field mapping that trigger it, resetting and reuploading leads safely, and confirming leads are reaching the dialer hopper once the import itself is fixed.

How the failure typically shows up

Before troubleshooting anything, confirm the pattern matches what VICIdial Lead Import System Failure actually does when phone validation rejects a batch. The reported symptoms usually include:

• CSV uploads appear successful on screen, but no leads land in the target list.
• The import process reports a BAD-PHONE validation error against some or all rows.
• The upload completes without any leads being inserted, and the list’s lead count does not move.
• The same result happens across different file formats and phone number layouts, ruling out a one-off formatting mistake.
• Testing across multiple CSV structures still points back to the lead-import and phone-number validation step, not the file transfer itself.

The clearest evidence is the lead count itself. If the list’s total stays flat after several import attempts, the upload is completed but insertion is failing silently at the validation layer, which is exactly what a BAD-PHONE rejection looks like from the admin panel.

Reproducing the fault step by step

Walking through the failure end to end makes the validation behaviour visible rather than assumed. The sequence below mirrors what KingAsterisk’s support team runs on every lead-import ticket.

Step 1: Open the load new leads screen

From Admin, go to Lists, select the target list, and open Load New Leads. This screen accepts the CSV, lets you map fields, and shows the import summary once processing finishes.

Step 2: Submit without a file attached

Clicking submit without selecting a CSV returns ERROR: No file uploaded. This confirms the form itself is functioning and rules out a broken submit action before moving to real data.

Step 3: Upload a correctly formatted CSV

With a properly structured file – clean header row, phone_number in the expected format, correct list and campaign selected – the import completes and the summary reports the number of leads inserted, updated, and rejected.

Step 4: Upload a deliberately malformed CSV

Reintroducing a bad phone number format, an extra delimiter, or a shifted column reproduces the BAD-PHONE rejection. The import summary reports rows rejected for phone validation instead of leads inserted, even though the upload itself completes without an error page.

Step 5: Re-upload the same file

Uploading the identical file a second time, without changing vendor_lead_code or resetting the list, returns an already-imported result rather than a fresh insert. This is VICIdial’s duplicate check working correctly, not a second failure.

What actually triggers the BAD-PHONE error

VICIdial validates phone_number during the load process before a row ever reaches the database. A row fails validation, and is reported as BAD-PHONE, for any of the following reasons:

• The number contains letters, spaces, brackets, dashes, or a leading plus sign that was not stripped before upload.
• The digit count falls outside the length VICIdial Lead Import System Failure expects for the configured numbering plan, which defaults to North American 10-digit formatting unless changed.
• The area code or prefix is not present in the system’s reference table, which matters for deployments serving Australian or other non-US number ranges running on default settings.
• The phone_number column is empty for that row because a header mismatch shifted data into the wrong field during mapping.

This last point explains why the same CSV can pass on one list and fail on another. If the column order in the file does not match the field mapping selected on the upload screen, VICIdial system reads a name, an address, or a blank cell as the phone number and rejects the row, even though the actual phone data further along the row is perfectly valid.

How to reboot VICIdial Lead Import System Failure Correctly

Most lead-import and hopper issues do not require a reboot, but a stalled dialer process occasionally does. Restart individual services rather than the full server where possible:

systemctl status mariadb
systemctl restart mariadb
systemctl restart httpd
systemctl restart asterisk

systemctl status mariadb
systemctl restart mariadb
systemctl restart httpd
systemctl restart asterisk

If the predictive dialing process itself has stalled rather than a background service, reconnect to its screen session (commonly astguiclient or AST_VDauto_predictive) and restart it from there rather than rebooting the whole machine. A full server reboot is only necessary after kernel or package updates, or when a service will not come back cleanly through systemctl. 

On an AlmaLinux deployment with a dedicated IP, confirm the reboot window with whoever manages the client-side server access before restarting, since it will drop any live calls in progress.

Related fault: manual dialing not responding after a lead import

A second issue sometimes surfaces around the same time as an import failure and gets mistaken for the same root cause: an agent logs in successfully, sees the Dial Next Number button, clicks it, and nothing happens – no outbound call, no screen update, no Asterisk origination. A quick database check confirms whether the agent session itself is the problem:

SELECT user, status, campaign_id
FROM vicidial_live_agents;
Returns:
TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN
A PAUSED status blocks manual dial actions even though the button remains clickable in the interface. Combined with the campaign's dial level setting:
Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

SELECT user, status, campaign_id
FROM vicidial_live_agents;
Returns:
TEST_AGENT | PAUSED | SAMPLE_CAMPAIGN
A PAUSED status blocks manual dial actions even though the button remains clickable in the interface. Combined with the campaign's dial level setting:
Campaign: SAMPLE_CAMPAIGN
auto_dial_level=0

This points to the agent session, not the lead data, as the cause. auto_dial_level=0 is the expected setting for manual dialing campaigns, so the fix is clearing the paused state and confirming the agent’s phone extension is registered, rather than re-checking the leads that were just imported.

Automating lead delivery so this stops recurring

Teams that hit BAD-PHONE errors repeatedly on manual CSV uploads are usually better served moving recurring feeds to a script-driven import through KingAsterisk’s REST integration layer, which returns a structured validation response instead of a generic upload summary. A lead import request looks like this:

POST /api/v1/leads
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "data": {
    "clientReferenceId": "CRM500001",
    "phoneNumber": "+18005551234",
    "firstName": "John",
    "listId": 1001,
    "campaignId": "OUTBOUND001",
    "vendorLeadCode": "RM10001"
  }
}
 
A rejected number returns a validation error naming the specific field and reason instead of a batch-level BAD-PHONE summary:
{
  "success": false,
  "code": 422,
  "message": "Validation Failed",
  "errors": [
    { "field": "phoneNumber", "message": "Phone Number is required." }
  ]
}
 

POST /api/v1/leads
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "data": {
    "clientReferenceId": "CRM500001",
    "phoneNumber": "+18005551234",
    "firstName": "John",
    "listId": 1001,
    "campaignId": "OUTBOUND001",
    "vendorLeadCode": "RM10001"
  }
}
 
A rejected number returns a validation error naming the specific field and reason instead of a batch-level BAD-PHONE summary:
{
  "success": false,
  "code": 422,
  "message": "Validation Failed",
  "errors": [
    { "field": "phoneNumber", "message": "Phone Number is required." }
  ]
}
 

and a lead that already exists returns a 409 duplicate response referencing the existing lead ID rather than silently discarding the row. For CRM-fed or vendor-fed campaigns running daily volumes, this level of per-record feedback catches formatting problems before they reach a hopper, which is a meaningfully faster diagnostic path than re-running a full CSV to find one bad column.

Frequently asked questions

Get lead import issues fixed properly

If BAD-PHONE errors, empty hoppers, or stalled manual dialing keep recurring on your VICIdial deployment, KingAsterisk Technologies can review your list configuration, phone validation settings, and campaign hopper filters directly, and set up a script-driven lead feed where manual CSV uploads are no longer practical. 

Reach out to discuss your current setup and get a fix that holds beyond the next upload.

If you’ve spent any time inside a stock VICIdial admin panel, you already know the feeling: dense tables, 2005-era form fields, and a navigation structure that hasn’t meaningfully changed in over a decade. That’s the exact gap KingAsterisk Technologies built its custom VICIdial admin themes to close. 

VICIdial’s underlying engine is rock solid – but the interface supervisors and administrators stare at for eight hours a day hasn’t kept pace with how contact centers actually operate in 2026. Every theme in this roundup is a proprietary, in-house build – not a community skin, not a third-party plugin, and not a repackaged open-source template. 

We design, code, and test each dashboard against live VICIdial and ViciBox deployments, then refine it based on direct feedback from supervisors managing real campaigns across industries like lead generation, appointment setting, collections, and customer support.

In this guide, we’re walking through the top 5 custom VICIdial admin themes currently available from KingAsterisk, what makes each one different, and how you can explore them yourself in our live demo environment before committing to a deployment.

Why a Custom VICIdial Admin Theme Actually Matters

It’s tempting to dismiss admin theming as cosmetic. It isn’t. A poorly organized dashboard adds seconds to every lookup a supervisor performs – and across hundreds of daily actions, that adds up to real lost floor time. A custom VICIdial admin theme changes three things that directly affect day-to-day operations:

Navigation speed – grouping campaign management, list management, and reporting into a logical, visual structure instead of VICIdial’s flat menu tree.

Onboarding time – new administrators and team leads learn a clean, modern layout faster than the stock interface’s dense forms.

Data legibility – real-time agent status, campaign statistics, and queue information are easier to scan at a glance, which matters most during peak call volume.

Brand consistency – for agencies and BPOs running the panel in front of clients, a themed dashboard looks like a purpose-built platform rather than an off-the-shelf install.

None of this changes VICIdial’s core dialing engine, campaign logic, or database structure. A custom admin theme is a presentation layer built on top of the existing VICIdial and Asterisk stack – the underlying system you already know still does the work.

The Top 5 Custom VICIdial Admin Themes from KingAsterisk

All five of these dashboards are custom VICIdial admin themes designed and maintained by KingAsterisk. Four are English-language administration interfaces built around different operational priorities. The fifth is a dedicated German-language dashboard, built for teams operating in DACH-region deployments who need the admin panel itself – not just campaign scripts – presented in German.

The Streamlined Operations Theme

This one is the entry point for teams moving off the stock VICIdial interface for the first time. It restructures the default admin menu into a card-based navigation layout, with campaign management, list management, and user administration grouped into clearly labeled sections instead of a long left-hand tree.

This theme keeps every native VICIdial function in place – nothing is hidden or removed – but reorganizes the visual hierarchy so the most frequently used screens (live agent status, campaign configuration, and lead search) sit one click from the home dashboard instead of three or four.

Best suited for: smaller teams and agencies making their first move to a custom admin theme without wanting to relearn where anything lives.

The Real-Time Monitoring Theme

The real-time monitoring theme is built for supervisors who spend most of their day watching live queues rather than running reports. The dashboard opens directly into a real-time monitoring view showing agent status, live call counts, and queue depth across active campaigns, refreshed continuously rather than requiring a manual page reload.

It also incorporates an Auto-Attendant management panel, giving administrators a visual editor for call-routing logic instead of navigating raw menu configuration screens. Routing rules, time-based conditions, and department transfers can be reviewed and adjusted from a single screen, which meaningfully cuts down the time it takes to update inbound routing during shift changes or campaign launches.

Best suited for: floor supervisors and operations managers who need at-a-glance visibility into live activity, and teams that frequently adjust inbound routing.

The Conversation Intelligence Theme

The conversation intelligence theme is built around post-call visibility. Alongside the standard VICIdial disposition and recording tools, this theme layers in a sentiment analysis module that flags calls likely to need supervisor review – tone shifts, extended silence, or abrupt call endings – without requiring a manager to listen to every recording end-to-end.

The sentiment view sits alongside disposition data and campaign statistics on the same dashboard, so quality assurance teams can move from a flagged call straight into the relevant lead record and agent history without switching screens.

Best suited for: quality assurance teams, coaching-focused supervisors, and campaigns where conversation quality directly affects conversion or compliance.

The Productivity Theme

The productivity theme is designed around after-call workflow speed. Its standout addition is a call summarization panel that condenses each completed call into a short, structured summary – key discussion points, disposition reasoning, and any follow-up flagged by the agent – displayed directly in the lead history.

For campaigns with high call volume and tight after-call work targets, this cuts down the time supervisors spend reconstructing what happened on a call from raw recordings or agent notes alone, particularly useful when handing a lead off between shifts or agents.

Best suited for: high-volume outbound campaigns, appointment-setting teams, and any operation where fast lead handoffs matter.

The German-Language Dashboard

The German Theme is the only theme in this list built as a fully localized German-language administration panel – menu labels, form fields, report headers, and system messages are presented natively in German rather than relying on a browser-level translation layer. This is the theme we deploy for clients running DACH-region operations who need administrators to work in their own language, not just agents.

This theme also includes a predictive analytics module, surfacing forward-looking indicators such as projected list exhaustion, expected connect rates for the remainder of a shift, and campaign pacing trends – presented as simple visual indicators rather than raw statistical output, so administrators can act on them without needing a background in data analysis.

Best suited for: contact centers operating in German-speaking regions, and any deployment where administrator-level localization is a requirement rather than a nice-to-have.

How KingAsterisk Builds Every Custom Theme

A custom VICIdial admin theme isn’t a drop-in skin – VICIdial installations vary enough in the ViciBox version and SVN codebase revision that a theme built for one environment can break on another if it isn’t matched correctly. Our build process accounts for that from the start.

Step 1: Environment Assessment

Before development starts, we confirm two details from your existing setup: your ViciBox version and your SVN (VICIdial codebase) revision. These determine which theme structure and file paths we can safely build against.

Step 2: Custom Development

The theme is developed specifically for your environment – not adapted from a generic template. Depending on the project, this can include a modern interface layer, updated dashboard components, and campaign management tooling built on top of your existing VICIdial installation.

Step 3: Delivery

Once development is complete, you have two options: we provide the source code and installation steps for your own team to deploy, or you provide server access and we handle installation and configuration directly.

Step 4: Ongoing Support

Several support packages are available for post-installation needs, scoped to your environment and update frequency requirements – we can walk through the right fit once your ViciBox and SVN details are confirmed.

How to Explore These Themes on the Live Demo

Every theme above can be explored before deployment through the KingAsterisk demo portal. Here’s the process, using the Global Admin theme as an example:

• Visit kingasterisk.com and select Live Demo from the main navigation.
• This opens the demo portal at demo.kingasterisk.com, where each available theme is listed.
• Choose a theme – for example, Theme 5 for the German-language Global Admin dashboard.
• Click Admin to reach the themed login screen, located at a custom path such as
• demo.kingasterisk.com/theme-5/dialer/admin.php
• Enter the demo credentials provided on the login page and sign in to explore the full dashboard.

Once logged in, you can navigate the complete admin panel – campaign management, agent administration, lead and list management, real-time reporting, and system monitoring – all through the selected theme’s interface, with full underlying VICIdial functionality intact.

A Security Note on Custom Admin Panel Paths

One side benefit of a custom theme deployment worth mentioning: the admin login path itself changes. A standard VICIdial installation serves its admin panel at a predictable, publicly documented location. A KingAsterisk custom deployment instead serves the panel at a client-specific path – commonly something like /dialer/admin.php rather than the default /vicidial/admin.php – which can be adjusted further per project.

Frequently Asked Questions

Final Thoughts

The stock VICIdial admin panel gets the job done, but it wasn’t built with today’s contact center pace in mind. Whether your priority is faster navigation, real-time visibility, post-call intelligence, faster after-call summaries, or a fully localized German-language experience for your administrators, there’s a custom VICIdial admin theme built for that specific need – not a generic reskin applied after the fact.

If you’re ready to see how any of these five themes look against your own ViciBox and SVN environment, reach out to KingAsterisk Technologies to start with an environment assessment, or head straight to the live demo to explore them yourself.

KingAsterisk Technologies designs, develops, and deploys custom VICIdial, Asterisk, and dialer interface solutions for contact centers worldwide. For more on our development services, visit our contact page. 

If you administer a VICIdial environment, you have probably seen VICIdial Permission Error.  This exact message pops up on a user’s screen: “You Do Not Have Permission to View This Page.” 

It usually happens right after a new user is created, an agent is promoted to a supervisor role, or a User Group is copied from an existing template. The login itself works fine – the username and password are correct – but the moment that user clicks into a specific admin page, VICIdial blocks the screen outright.

This is not a bug. It is VICIdial’s permission system doing exactly what it was designed to do: gate every admin page behind a specific permission flag stored against the User Group and User Level. In this guide, we will break down what triggers the error, how to trace it back to the exact permission responsible, and how to fix VICIdial user permissions correctly – the same process our support team follows when clients report this issue on their deployments.

What Does the VICIdial Permission Error Mean?

VICIdial’s admin interface is built as a large collection of individual PHP pages – one for managing users, one for campaigns, one for lists, one for each report, and so on. Every one of these pages runs a permission check at the very top of the script, before any data or form loads. That check looks at two things stored in the vicidial_users and vicidial_user_groups tables: the logged-in user’s User Level, and the specific permission flags attached to that user’s User Group.

When the check passes, the page renders normally. When it fails, VICIdial stops execution immediately and prints the message: “You Do Not Have Permission to View This Page.” No data is shown, no partial page loads – the script exits as soon as the permission check returns false.

This distinction matters for troubleshooting. A login failure means the username or password is wrong, and the user never reaches the dashboard at all. 

A permission error means authentication succeeded – the user is genuinely logged in – but authorization failed for that particular page. The fix, therefore, is never about resetting a password. It is about locating and correcting the specific permission flag tied to the page the user is trying to open.

How to Identify the Permission Causing the Error

Every admin page in VICIdial is mapped to a corresponding permission field inside the User Group configuration (and in some cases, an individual toggle on the User record itself). These fields store a simple binary value.

Permission Value 1 – Page Accessible

When the relevant permission field is set to 1, the permission check passes and the page loads exactly as expected. For example, if “Modify Campaigns” is set to 1 for a User Group, any user in that group can open the campaign editing screen without issue.

Permission Value 0 – “You Do Not Have Permission to View This Page”

When that same field is set to 0, VICIdial blocks the page entirely and displays the error message. This is the exact behavior admins run into after cloning a restrictive User Group template, or after a manager account is downgraded without adjusting individual toggles.

To trace the correct field, match the page the user was trying to reach against its corresponding permission name in the User Group screen. Some of the most common mappings include:

• Admin – Users pages – controlled by Modify Users / Delete Users
• Admin – Campaigns pages – controlled by Modify Campaigns
• Admin – Lists / lead upload pages – controlled by Load Leads / Modify Lists
• Reports section (Agent Time, Call Detail, etc.) – controlled by View Reports plus the Allowed Reports list
• Any page under Admin – User Groups – controlled by Modify User Groups

Once you know which permission name corresponds to the blocked page, the fix is a straightforward edit inside that user’s User Group.

Step-by-Step: How to Fix the VICIdial User Permission

The steps below cover both a general permission fix and the more specific case of restricting a user to a single report – a very common request when a manager should only see Agent Time data and nothing else.

1. Log into the VICIdial admin panel using an account with sufficient User Level (typically Level 1, full administrator access).

2. Navigate to Admin – User Groups – Show User Groups.

3. Locate the User Group assigned to the affected user and click the Edit (Action) icon.

4. Scroll to the permission field that matches the blocked page (for example, Allowed Reports, Modify Campaigns, or Modify Lists) and change the value from 0 to 1.

5. If you are restricting access rather than opening it up – for example, giving a manager visibility into only the Agent Time Detail Report – create a dedicated User Group first (e.g., REPORT_USERS), then set Allowed Reports to only the report you want visible.

6. Create or edit the User record under Admin – Users. Assign the correct User Group, set User Level to 7 or 8 for report-only access, and set View Reports = 1 while leaving Modify Users, Modify Campaigns, Modify Lists, Delete Users, and Load Leads at 0.

7. If report visibility should also be limited by team, configure Allowed User Groups inside the User Group settings so the group can only see report data belonging to specific other groups.

8. Click Save Changes to commit the updated permission set.

This combination – User Level, User Group, View Reports, and Allowed Reports – is how VICIdial layers access control. Getting all four aligned is what separates a user who can see everything from one who can see exactly one report and nothing else.

How to Test the Permission After Making Changes

Permission changes in the VICIdial solution are not applied to an already-open session. The permission set is read once, at login, and cached for that session. Always have the affected user log out completely and log back in before assuming a fix has failed.

• Log in as the affected user (or ask them to) in a fresh browser session or private window.
• Navigate directly to the page that previously triggered the error.
• Confirm the page now loads and displays data as expected.
• If the report-only scenario was configured, confirm that only the intended report appears and that other admin menu items remain hidden.
• If the error persists, double-check that the user is actually assigned to the updated User Group – not a similarly named group left over from a previous setup.

Common VICIdial Permission Issues

Most permission errors trace back to one of a small handful of causes:

User assigned to the wrong User Group – the permission was fixed on one group, but the user’s account still points to a different one.

User Level too low – some pages require a minimum User Level regardless of what the User Group allows, so both gates need to agree.

Stale session – the user tested the page without logging out first, so the old cached permission set was still active.

Custom admin panel paths – on customized deployments the admin interface may live at a different path (for example /dialer/admin.php instead of the standard /vicidial/admin.php); the underlying permission logic is identical, but it helps to confirm you are editing the correct environment.

Allowed Reports vs. general admin toggles confused with one another – restricting a report requires editing Allowed Reports specifically, not the general Modify permissions.

Allowed User Groups left unconfigured – the user has View Reports enabled but still cannot see data belonging to another team’s group.

Watch: Fixing the VICIdial Permission Error

This walkthrough shows the exact VICIdial permission error on screen and demonstrates the User Group fix in real time – useful if you’d rather watch the fix than read it.

Need Setup or Server Support?

If you are configuring User Groups, Allowed Reports, or a full permission structure on a new environment and want it set up correctly from the start, our team can assist with both the permission architecture and the underlying server environment.

Server Information

1. Hardware suggested based on your requirements
2. Intel and AMD hardware options available
3. Installation and configuration support
4. Compatible with multiple server environments

Important Note

• AlmaLinux server required from client side
• Dedicated IP required for setup
• Server access needed for installation
• Installation support provided

Frequently Asked Questions

Final Thoughts

The “You Do Not Have Permission to View This Page” message in VICIdial is a straightforward access-control response once you know where to look. Every blocked page maps back to a specific permission field inside the User Group or User configuration, and correcting it is a matter of locating that field, flipping it to the right value, and having the user log back in to pick up the change.

If your team manages multiple User Groups, custom admin panel builds, or a large agent roster and wants a permission structure that is easier to maintain long-term, KingAsterisk Technologies works with VICIdial and Asterisk environments on exactly this kind of configuration – from user access control to full custom admin panel builds. 

Reach out to our team to have your permission structure reviewed and set up correctly.