2026

Every contact center that runs on VICIdial generates a significant volume of call recordings. The root of most of these problems is a poorly understood or misconfigured VICIdial recording path. These recordings serve legal, quality assurance, compliance, and training purposes. 

Yet many operations struggle with the same recurring problems: recordings go missing, storage fills up without warning, file retrieval takes too long, or recordings land in the wrong directory entirely.

When you know exactly how VICIdial handles recordings, where the files go, and how to manage the directory structure intelligently, most of these issues disappear.

This guide covers everything from the default VICIdial recording path configuration to advanced storage management, security hardening, and custom development options for growing operations.

How the VICIdial Recording Path Works

VICIdial stores call recordings as audio files on the server running Asterisk. Each recording is written to a directory path that VICIdial constructs based on parameters you define in the system configuration. Understanding this path structure is the first step toward managing recordings effectively.

The Default Recording Directory Structure

Out of the box, VICIdial saves call recordings to:

/var/spool/asterisk/monitor/

/var/spool/asterisk/monitor/

Within this directory, VICIdial stores recordings according to the configured recording and file-management setup. Depending on the installation, completed recordings may be moved to a separate directory such as monitorDONE.

A recording file’s name and directory structure depend on the system configuration. The filename may contain details such as the campaign name, date, timestamp, and call ID, depending on the configured naming convention.

Where Is My Call Recording Saved?

This is one of the most common questions from new VICIdial administrators. The short answer: your recording is saved on the Asterisk server at the path configured in your VICIdial admin panel under Admin > System Settings > Recording.

The full path depends on:

• The base recording directory configured in VICIdial
• The date the call was made (year/month/day subdirectory)
• The campaign name
• The call timestamp and unique leg ID

If you have modified the default path or use a custom recording location, check your /etc/asterisk/ configuration files, specifically extensions.conf and any custom dialplan includes, for path overrides.

Where Are FreePBX Call Recordings Saved?

FreePBX and VICIdial both use Asterisk as the underlying telephony engine, but they manage recordings differently. FreePBX typically saves recordings to:

/var/spool/asterisk/monitor/

/var/spool/asterisk/monitor/

However, FreePBX also uses the Call Recording module, which may redirect recordings to:

/var/spool/asterisk/monitor/YYYY/MM/DD/

/var/spool/asterisk/monitor/YYYY/MM/DD/

The key difference is that FreePBX abstracts the recording path through its GUI, while VICIdial exposes more granular control at the admin level. In a VICIdial environment, administrators have direct access to the Asterisk recording path without needing to navigate a separate module, which gives more flexibility for custom storage configurations.

VICIdial Recording Path Configuration Options

VICIdial provides several levers for controlling where and how recordings are stored. Understanding each one helps you design a storage architecture that matches your operational volume and retention requirements.

Setting the Base Recording Path

In the VICIdial admin panel, navigate to Admin > System Settings. The “Recording Filename” and related fields let you define how recording filenames are constructed. You can incorporate variables like ${CALLID}, ${CAMPAIGN}, ${CURDATE}, and ${AGENT} to build a path and filename that works for your reporting and retrieval workflows.

Per-Campaign Recording Paths

VICIdial allows you to override the recording path at the campaign level. This is useful when you run multiple clients or business units on the same VICIdial instance and need to physically separate their recordings on disk. Campaign-level path overrides let each campaign write to its own subdirectory, simplifying access control and billing for storage.

Inbound and Outbound Recording Differences

Outbound recordings are triggered by the campaign’s dial settings. Inbound recordings are typically configured through the inbound group settings. The VICIdial recording path applies to both, but the trigger mechanism differs. For inbound queues, you configure recording in the Inbound Groups section, and the recording follows the same path structure.

If your agents are using softphones or WebRTC browser phones connected to VICIdial, their recordings are managed by the VICIdial recording path on the server, not by any mobile dialer application.

For any agent using a mobile device as part of a VICIdial deployment (via SIP client or WebRTC), the server-side VICIdial recording path is what governs recording storage, not the mobile device.

Common VICIdial Recording Path Problems and Solutions

Even well-configured VICIdial systems develop recording issues over time. Here are the most frequent problems and their causes:

Diagnosing a Missing Recording

If a specific recording is missing, work through this sequence:

1. Confirm the call actually completed (check vicidial_log in the database)
2. Verify the recording flag was enabled for that campaign
3. Check the Asterisk server at the expected VICIdial recording path using the call date and ID
4. Review /var/log/asterisk/full for MixMonitor errors around the call time
5. Check disk space and inode counts with df -h and df -i

Storage Management for Large-Scale VICIdial Deployments

A contact center handling 500+ agents can generate several terabytes of recording files each month. Without a structured storage management approach, the VICIdial recording path directory fills up, recordings start failing silently, and retrieval becomes slow.

Organizing Recordings for Long-Term Storage

The default date-based directory structure works well for short-term access but becomes unwieldy for long-term retention. A better approach for large deployments is to implement a secondary organization layer by client, campaign, or year-month, with automated scripts that move recordings from the active directory to an archive location after a configurable retention window.

Monitoring Disk Usage on the Recording Partition

Set up monitoring on the partition that holds your VICIdial recording path. A practical threshold is to alert at 75% usage and take automated action (archival, compression, or deletion of recordings past retention period) at 85%. Ignoring disk usage on the recording partition is the single most common cause of recording failures in production VICIdial environments.

Compressing Older Recordings

WAV files can require substantial storage space. For recordings that are accessed infrequently, an appropriate compression or archival strategy may reduce storage requirements.

Before converting recordings to another format, verify audio-quality requirements, compliance obligations, playback compatibility, and whether the VICIdial interface supports the resulting files. Do not assume that changing a file extension or moving a recording will automatically update its database reference. Test the process with sample recordings before applying it to production data.

Securing the VICIdial Recording Path

Call recordings contain sensitive customer data. PCI DSS, HIPAA, GDPR, and most local contact center compliance frameworks require that recordings be stored securely with access controls, audit trails, and defined retention policies.

File System Permissions

The recording directory should be owned by the asterisk user and group. Web server processes and VICIdial PHP scripts need read access to serve playback, but no process outside of Asterisk should have write access to the base recording directory. A common misconfiguration is setting the recording directory to world-writable, which creates a significant security exposure.

chmod 750 /var/spool/asterisk/monitor
chown -R asterisk:asterisk /var/spool/asterisk/monitor

chmod 750 /var/spool/asterisk/monitor
chown -R asterisk:asterisk /var/spool/asterisk/monitor

Restricting Playback Access by Role

VICIdial’s built-in user permissions allow you to restrict recording playback to supervisors and QA staff. Agents should not have playback access to their own or other agents’ recordings in most compliance environments. Audit the VICIdial user level permissions regularly to confirm that recording access matches your data governance policy.

Encryption at Rest

For PCI DSS-scoped environments, recordings that contain card data must be encrypted at rest. VICIdial does not natively encrypt recording files, but you can implement filesystem-level encryption on the recording partition using LUKS, or post-record encryption using a custom AGI script that encrypts the file immediately after MixMonitor closes it.

Custom VICIdial Recording Path Development by KingAsterisk

KingAsterisk builds custom recording management solutions for VICIdial deployments at every scale, from single-server setups handling a few dozen agents to multi-server architectures processing millions of calls per month.

What We Develop

Our recording path customization work covers:

Custom recording directory structures

We design and implement directory layouts that match your client segmentation, compliance requirements, and storage infrastructure, rather than the default single-path model.

Automated Archival and Retention Systems

Scripts and scheduled jobs that move, compress, or delete recordings based on configurable retention rules per campaign or client.

Recording Storage Optimization

Database query optimization for large vicidial_recordings tables, index tuning for fast retrieval, and MariaDB performance improvements for deployments with hundreds of millions of recording records.

Secure Recording Delivery APIs

Custom API endpoints that let authorized external systems (CRM platforms, QA tools, workforce management software) retrieve recordings by call ID without exposing the underlying VICIdial recording path or server filesystem.

Multi-Tenant Recording Isolation

For SaaS contact center platforms and VICIdial resellers, we build recording architectures that completely separate data at the filesystem and database level, ensuring one tenant’s recordings are never accessible to another.

Custom Recording Management Dashboards

Supervisor and admin interfaces that surface recording search, playback, download, and retention management without requiring direct server access.

Frequently Asked Questions

Why the VICIdial Recording Path Deserves Dedicated Attention

Most VICIdial deployments treat recording path configuration as a one-time setup task. It is not. As call volume grows, as compliance requirements change, and as storage costs accumulate, the recording path configuration becomes a recurring operational concern.

Getting it right from the start means fewer production incidents, faster recording retrieval, cleaner storage cost management, and a defensible position when regulators ask how customer data is stored and protected.

Whether you need a targeted fix for a specific recording problem or a complete redesign of your recording storage architecture, KingAsterisk has the VICIdial depth to do it correctly.

Get in touch with our team to discuss your recording path requirements, storage challenges, or compliance needs.

When a contact center deploys VICIdial for a German-speaking market and leaves the interface in English, it creates a silent operational problem. A custom VICIdial German theme solves this at the source. Agents are reading menus, buttons, and status labels in a language that may not be their first. 

Supervisors are monitoring dashboards with terminology that does not match how their team thinks or communicates. Scripts are displayed in German, but the system prompts around them are not.

The friction this creates is small per interaction, but it compounds. Wrong disposition selections. Pause codes that mean something different to the agent than to the supervisor. Forms filled out in the wrong field because the label was misread. These are not dramatic failures – they are the kind of quiet inefficiency that erodes productivity and data quality over months.

This post covers what that development work actually involves, what it changes for agents and supervisors, and why off-the-shelf localization approaches tend to fall short for serious deployments.

What “Custom VICIdial German Theme” actually means in VICIdial

People sometimes use “language theme” to mean a translated interface – swap the English text for German and you are done. That understanding misses most of what a genuine localization build requires.

A VICIdial German language theme is a development project that spans three layers:

Interface text and labels 

Every visible string in the VICIdial agent interface, supervisor panel, and admin area needs to be reviewed, translated with operational accuracy (not just linguistic accuracy), and replaced. This is not a find-and-replace job. 

VICIdial’s interface contains hundreds of labels, tooltips, status messages, and confirmation dialogs. Many of them use technical contact center terminology that has no direct German equivalent and requires a deliberate choice about which term to use for a German-speaking team.

Visual layout and display logic

German words are typically longer than their English equivalents. A button that fits cleanly at its current size in English – “Disposition” – may overflow or truncate when replaced with “Gesprächsergebnis.” This is not a minor cosmetic issue. Truncated labels in a contact center interface mean agents cannot reliably read what they are clicking. Layout adjustments, font sizing, and field width changes are part of the localization work, not afterthoughts.

Functional behavior tied to locale

Date formats, time formats, number formats, and sorting behavior may all need adjustment. German business environments use DD.MM.YYYY date formatting by default. Phone number display formats differ. If your VICIdial deployment feeds data into German CRM systems or reporting tools, the data format your interface produces needs to match what those systems expect.

Why standard VICIdial language files are not enough

VICIdial does support language file customization through its built-in localization architecture. You can edit the language strings in the source and switch the interface language. For basic deployments, this works. For a production deployment serving German-speaking agents at any meaningful scale, it runs into limitations quickly.

The language files cover system strings – what VICIdial ships with. They do not cover:

• Custom fields your team has added to agent screens
• Custom disposition codes you have configured for your campaigns
• Custom pause code labels your supervisors use for attendance and break tracking
• Script display areas, which are typically managed outside the core language file system
• Custom reporting interfaces and dashboard labels if you have extended VICIdial’s reporting module
• Any custom widgets, panels, or integrations that have been added to the interface

If your VICIdial deployment has been customized – and most production deployments have – those customizations exist outside the scope of the standard language file. They need to be localized separately, and that requires working in the codebase directly.

There is also the matter of consistency. A deployment where some labels are in German (the standard system strings) and others remain in English (everything that was added later) is not a localized interface. It is a mixed-language interface, and mixed-language interfaces are harder to use than fully English ones because agents cannot build reliable mental models of what to expect.

What a Custom VICIdial German Theme development project covers

When KingAsterisk builds a custom VICIdial German theme, the scope covers the complete agent experience – not just the parts VICIdial ships with.

Agent screen localization

The agent screen is where most of your staff spends their working day. Every element needs to communicate clearly in German: the call status display, the lead information panel, the disposition dropdown, the callback scheduler, the script display area, the manual dial interface, and any custom fields your campaigns use.

We audit the full agent screen for every element – system-generated and custom – and produce a localized version where German is the consistent working language throughout. For custom fields and disposition codes, we work with your operational team to confirm the correct German terminology before implementation, since these terms often reflect internal business logic that a direct translation would not capture.

Supervisor and monitoring panel localization

Supervisors working in German need dashboards and monitoring panels that match their language context. This includes the real-time monitoring screen, agent status labels, queue displays, and any custom supervisor panels your deployment includes.

One area that often gets missed: the pause code display in supervisor monitoring shows why agents are not on calls. If your pause codes are configured with English labels (“Lunch”, “Training”, “Break”) and your supervisors are German-speaking, the reporting accuracy suffers because supervisors and agents may be using the codes inconsistently. Localizing pause code labels is part of the supervisor panel work.

Reporting and data export labels

Standard VICIdial reports contain headers, column labels, and filter options. If your team exports these reports for review by German-speaking managers or clients, English-language column headers create an extra translation burden at the point of use. We localize report interfaces and, where reports are exported to spreadsheets or PDFs, ensure the output labels are in German by default.

German-language script display

Agent scripts in VICIdial are typically managed through the script editor. For a German market deployment, scripts are almost certainly already in German. What needs attention is everything around the script: the instruction labels, the section headers, the product information display areas, and any dynamic data that gets pulled into the script from your lead database. 

If your script pulls a customer’s name, company, or contract details into the display, that data and its surrounding labels need to be consistent.

IVR and voicemail interface elements

If your VICIdial deployment includes inbound IVR menus or voicemail configuration through the admin panel, these also need German-language treatment for the staff who configure and maintain them. The customer-facing IVR audio is typically already in German for a German market; the back-end configuration interface for your telephony team should be as well.

The Compliance Dimension: Why This Matters in Germany 

Germany has a specific regulatory environment for outbound contact center operations. The Federal Network Agency (Bundesnetzagentur) and data protection regulations under the BDSG and GDPR create compliance requirements that affect how calls are made, how consent is recorded, and how data is handled.

When your VICIdial deployment serves the German market, the accuracy of your disposition data and call records is not just an operational concern – it affects your compliance documentation. If agents are selecting dispositions incorrectly because they misread English-language options, your compliance records contain errors. 

If your call data exports use date and time formats that do not match German regulatory reporting standards, correcting those records is additional work at audit time.

A German language theme reduces this compliance risk by removing the interface ambiguity that leads to data entry errors. When every label in the system clearly communicates its meaning to a German-speaking agent, the rate of incorrect dispositions and form errors goes down – and your compliance documentation becomes more reliable.

Technical approach: how the Custom VICIdial German Theme build works

A custom VICIdial German theme is not a plugin or an add-on. It is a customization of the VICIdial codebase combined with custom frontend work, depending on the scope of your deployment.

For deployments running standard VICIdial, the work is primarily in the PHP files that generate the agent and supervisor interfaces, the language string files, the CSS that controls display and layout, and any JavaScript that handles dynamic interface behavior.

For deployments that have already been customized or require a modern interface, the localization work involves adapting the relevant interface elements, language strings, styling, and functionality to provide a consistent German-language experience. 

This is the better architecture for long-term maintenance, because adding new interface features later requires only adding new strings to the translation file, not re-localizing the component code.

KingAsterisk builds custom German-language VICIdial themes for both existing and new deployments. For legacy VICIdial systems, we customize the existing codebase, while new builds and major interface upgrades focus on creating a modern, user-friendly interface with consistent German translations, improved layouts, and easier long-term maintenance.

What changes for agents day to day

The operational impact of a fully localized German interface shows up in the metrics that matter for contact center performance.

Disposition accuracy

When agents select call outcomes from a German-language dropdown with clearly labeled options, they select the correct option more often. This improves your campaign data, your reporting accuracy, and your callback scheduling.

Average handle time

Agents who can navigate their interface without a cognitive translation step move through wrap-up work faster. For high-volume campaigns, even a few seconds per call adds up to meaningful productivity differences over a day.

New agent onboarding

Training new German-speaking agents on a German-language interface is faster and produces fewer early mistakes. You are teaching them the contact center workflow, not simultaneously asking them to work through an English interface they may not be entirely comfortable with.

Error rates on custom forms

If your campaigns use custom fields for lead qualification, contract data, or compliance checkboxes, German-language labels reduce the rate of fields filled incorrectly or left blank.

What this does not include

It is worth being direct about scope. 

A German language theme is a localization project. It does not change the underlying telephony behavior of your Custom VICIdial German Theme deployment, the dialing algorithms, or the integration logic with your CRM. It changes the interface that agents and supervisors interact with.

If your deployment has separate issues – SIP trunk instability, CRM integration problems, campaign configuration questions – those are separate projects. Some operations bundle a German theme build with a broader deployment upgrade or CRM integration project, which can make sense from a scheduling and cost standpoint, but the localization work is distinct from those other scopes.

How to approach the project

For organizations running existing VICIdial deployments that serve German-speaking agents, the starting point is an audit of the current interface – both the system components and any custom elements – to establish the full scope of what needs localization. This produces a complete string inventory and identifies any layout or data format issues that need to be addressed alongside the translation work.

For organizations building a new VICIdial deployment for the German market, localization architecture decisions should be made at the start of the project, before the interface is built, to avoid doing the same interface work twice.

KingAsterisk provides both German language theme development for existing deployments and German-first interface builds for new deployments. The timeline and scope depend on how extensively your current system has been customized and what your existing codebase looks like.

Frequently asked questions

Work with KingAsterisk

KingAsterisk provides Custom VICIdial German Theme development, including German language theme builds, for contact centers and communication operations globally. If you are running a German-market operation on VICIdial and want to assess what a full localization project would involve for your specific deployment, contact us to start with an interface audit.

We work with both legacy VICIdial deployments and modern customized VICIdial interfaces, and we handle the full scope from string translation to layout adjustment to data format alignment.

Open the VICIdial real-time screen at 10:15 on a busy morning and you can see most of what is happening on the floor. You can see who is talking, who is paused, who is stuck in wrap-up, and whether the dialer is moving. VICIdial Real Time Reporting puts all of that on one page that refreshes every few seconds.

Many supervisors only glance at the colors. This guide shows what each field means, which numbers to watch, and what to do when something looks wrong.

What Is VICIdial Used For?

VICIdial is an open-source platform built on Asterisk. Teams use it to:

• Run outbound campaigns with predictive, ratio or manual dialing
• Take inbound calls through ingroups and IVR menus
• Blend inbound and outbound on the same agents
• Manage lead lists, call scripts, dispositions and recordings
• Pull reports on agents, campaigns and lists

Sales teams, collections teams, surveys and support desks all run on it. The real-time report is how supervisors watch it work.

What Are Real-Time Reports?

Real-time reports are live screens that refresh on a timer. A normal report tells you what happened yesterday. VICIdial Real Time Reporting tells you what is happening right now, such as which agent is on a call, how long the longest hold is, and how many leads remain in the hopper. Use real-time reports to react. Use the historical reports to analyze trends.

VICIdial Real Time Reporting Login: How to Open It

1. Go to https://YOUR-SERVER/vicidial/admin.php.
2. Log in with a user account that has permission to access the Real-Time Main Report and the relevant campaigns.
3. Open Reports and click Real-Time Main Report.

You can also go straight to https://YOUR-SERVER/vicidial/realtime_report.php. The main report itself is served by AST_timeonVDADall.php, which is the script behind the page you will see most often.

If the login works but the report is blank, check the user’s report permissions and the allowed campaigns and user groups for that account. A restricted user group will hide everything outside it.

Report Options at the Top

Before you read any numbers, set the view. The options bar controls what you see:

• Campaign / group select: pick one campaign, several, or all.
• Refresh rate: 4 to 8 seconds is usual for a supervisor screen.
• Display options: show or hide phones, server details, call IDs and more.
• Inbound: include inbound groups so you can see queue calls.

Most of these map to URL parameters, so you can bookmark a saved view. More on that below.

Reading Agent Status in VICIdial Real Time Reporting

The agent grid is the part you look at most. Each row is one logged-in agent.

The statuses that matter:

• READY: logged in and waiting for a call.
• INCALL: on a live call.
• PAUSED: not taking calls (a break, a meeting, or a pause code).
• DISPO: the call has ended and they are choosing a disposition.
• DEAD: the call dropped on the agent’s end, and the agent is still on the screen.
• CLOSER: the agent is waiting on an inbound or transferred call.

The timer matters more than the status. An agent in READY for 10 seconds is normal. An agent in READY for 3 minutes means the dialer is not feeding them leads. An agent in DISPO for 20 seconds is fast. An agent in DISPO for 3 minutes is a training issue or a quiet break. Colors shift as the time grows, so a quick scan shows you which rows need attention.

Compare agents side by side. If one agent has 47 calls and the next desk has 28, ask why. It could be longer talk time, more pauses or a disposition habit.

Campaign Statistics in VICIdial Real Time Reporting

The top of the report shows the health of each campaign. These are the fields to watch:

• Dial level: how aggressively the dialer is placing calls per available agent.
• Dialable leads: leads left that can legally be called right now.
• Hopper level: how many leads are loaded and ready.
• Calls ringing / waiting: live calls in progress and calls waiting on an agent.
• Agents logged in / in call / ready / paused: the floor in four numbers.
• Calls today / drops today / drop percentage: your compliance numbers.
• Average hold time: how long answered calls wait for an agent.

The two numbers to check first are the drop percentage and the hopper. 

Drops are answered calls with no agent available. Monitor the campaign’s drop rate closely and follow applicable telemarketing regulations. If the drop rate rises, lower the dial level or review agent availability.

If the hopper hits zero, the dialer has nothing to call. Check these in order:

1. The list is set to Active.
2. The campaign’s lead filter is not too narrow.
3. The leads are inside their allowed calling hours for their timezone.
4. The AST_VDhopper process is running through cron.

A VICIdial Real Time Reporting Example

Here is a simplified view of what a supervisor might see on a Tuesday morning:

Campaign: SALES01   Dial level: 3.0   Hopper: 412   Drops today: 14 (1.8%)

Campaign: SALES01   Dial level: 3.0   Hopper: 412   Drops today: 14 (1.8%)

Reading it takes ten seconds. Agent 1011 has been paused for almost eight minutes with only 12 calls, so find out why. Agent 1015 has been in DISPO for over two minutes, so check whether the disposition list is confusing. Agent 1004 and 1007 look normal. Drops are at 1.8%, which is inside the limit.

That is the point of VICIdial Real Time Reporting. The screen shows you which rows to look at before the day’s numbers slip.

Monitoring Features: Listen, Whisper and Barge

From the real-time screen you can step into a live call. These are the options next to an INCALL agent:

• Listen (monitor): hear the call silently. Neither side knows.
• Whisper: talk to the agent only. The customer cannot hear you.
• Barge: join the call and speak to both sides.

To use them, your own phone or softphone must be registered and entered as the monitoring extension. Your user also needs monitoring rights. If you can hear the customer during a whisper, check the call routing and the extension you entered.

Listening to a handful of calls every day tells you more about agent quality than any number on the report.

Controlling Agents From the Screen

Supervisors can also act on what they see. Depending on your permissions you can:

• Log an agent out if their session is stuck
• Force a status change on a frozen agent
• Open the agent’s call record and lead details

Use these sparingly. Forcing changes on a live agent can cut off a call.

Customizing the Report with URL Parameters

Every option on the screen is also a URL parameter. A saved URL gives each supervisor the exact view they need:

https://YOUR-SERVER/vicidial/realtime_report.php?RR=8&groups[]=SALES01&adastats=2&NOLEADSalert=1

https://YOUR-SERVER/vicidial/realtime_report.php?RR=8&groups[]=SALES01&adastats=2&NOLEADSalert=1

• RR sets the refresh rate in seconds.
• groups[] picks the campaign.
• adastats turns on extra dialer statistics.
• NOLEADSalert warns you when a campaign runs out of leads.

Parameter names can differ a little between VICIdial versions, so check the options on your own report page and copy the URL it produces.

For a wall display, open one campaign per monitor with a refresh of 5 to 6 seconds. Anything faster adds load without telling you anything new.

Common Problems with VICIdial Real Time Reporting

Agents show READY but no calls are coming. Check the hopper first, then the dial level, then whether the trunk is registered. Run asterisk -rx “sip show peers” (or pjsip show endpoints) to confirm the carrier is reachable.

Agent status stuck or not updating. The agent may have closed the browser without logging out. A stale row stays in the vicidial_live_agents table until the keepalive process cleans it up. Check that the AST_manager_kill_hung_congested and the other VICIdial cron processes are running.

The drop rate suddenly spiked. Look for a sudden drop in agents, a carrier delay or a dial level that is too high for the number of agents logged in. Lower the dial level first and investigate second.

The report loads slowly. It reads straight from MySQL. Large campaigns, an overloaded database and a very short refresh rate all slow it down. Raise the refresh rate to 8 to 10 seconds, narrow the campaign selection, and check for long-running queries.

Pulling Live Data Without the Screen

For a custom wallboard you can read the same data directly. A quick, read-only look at who is logged in:

SELECT user, status, campaign_id, calls_today, last_state_change
FROM vicidial_live_agents
ORDER BY campaign_id, user;

SELECT user, status, campaign_id, calls_today, last_state_change
FROM vicidial_live_agents
ORDER BY campaign_id, user;

You can also use the Non-Agent API. The logged_in_agents function returns the logged-in agents for a campaign:

https://YOUR-SERVER/vicidial/non_agent_api.php?source=dashboard&user=APIUSER&pass=APIPASS&function=logged_in_agents&campaign_id=SALES01

https://YOUR-SERVER/vicidial/non_agent_api.php?source=dashboard&user=APIUSER&pass=APIPASS&function=logged_in_agents&campaign_id=SALES01

The API user must have API access enabled, and your server’s IP must be allowed. Never write to the live tables. Only read from them.

Keep API polling to every 5 to 10 seconds. Our team also builds custom dashboards and reports views around these endpoints, and you can see examples on the VICIdial customization page. If you are also setting up browser-based calling, our guide to the VICIdial Web Client covers that side.

A Daily Checklist for Supervisors

1. Start of shift: confirm everyone is logged in and the hopper is above your minimum.
2. Every 30 minutes: check drops, dial level and anyone with a long PAUSED or DISPO time.
3. Midday: listen to two or three calls from different agents.
4. Shift change: make sure old sessions are logged out so they do not clutter the screen.
5. End of day: note anything odd and compare it with the historical reports.

VICIdial Real Time Reporting only helps if someone acts on what it shows. A five-minute habit like this catches most problems early.

Frequently Asked Questions

Final Thoughts

VICIdial Real Time Reporting is free, it is already built into your system, and it shows you everything happening on the floor. Learn the statuses, watch the timers and check the drop rate and hopper first. 

Save your views as URLs and keep your monitoring extension ready. If you want the screen reshaped for your team, with different columns, a cleaner layout or a wallboard, our team can build it. Talk to us about custom VICIdial reports.

Every agent on a VICIdial system works from a single screen. That screen is the VICIdial Web Client, and it opens in a normal browser tab. There is no program to install and no softphone license to buy. This guide explains what the client does, how agents sign in, how browser calling is set up, how scripts work, and how to fix the errors we see most often.

What is the VICIdial Web Client?

The VICIdial Web Client is the agent side of VICIdial. It is a set of PHP pages that Apache serves from the /agc/ folder on your web server. The main page is vicidial.php, so the address on a typical system looks like:

https://dialer.example.com/agc/vicidial.php.

https://dialer.example.com/agc/vicidial.php.

MariaDB stores the leads, users and campaigns. Asterisk places and receives the calls. The page checks in with the server about once a second, which is why lead details show up the moment a call connects.

Some people search for it as the agent web client. The name changes, but the page is the same: the place where an agent logs in, takes calls, reads a script and picks a disposition.

Is VICIdial a dialer?

Yes. VICIdial is a dialer first and also handles inbound calls. Each campaign has a dial method that decides how numbers are called.

Whatever the dial method, the VICIdial Web Client is where the agent sees the result: a live call and a lead on screen.

What is VICIdial used for?

Teams use VICIdial for outbound sales and lead follow-up, collections, appointment reminders, surveys and political polling, and inbound queues with IVR menus. Many run a blended setup where agents take inbound calls and drop back to outbound dialing when the queue is empty. Call recording, reports and DNC list handling come with the system, so a small team can start on one server and move to a cluster later.

Can I use VICIdial for free?

Yes. VICIdial is open source under the AGPLv2 license and has no per-agent fee. You can install it and run it for as many agents as your hardware supports.

Free covers the software only. Someone still has to install it, tune it, keep Asterisk and MariaDB updated and fix problems on a busy day.

How much does VICIdial cost?

There is no license price, so the cost is everything around the software.

• One all-in-one server is enough for a small team. Larger teams split the database, web and telephony roles across separate machines.
• SIP trunks and phone numbers are usually the biggest running cost, because carrier minutes grow with call volume.
• Paid support, custom features and training are optional but common.
• Admin time goes into reports, list loading and updates.

Agent count, call volume and dialing countries differ for every team, so any single price you read online is a guess. A fair estimate needs those three numbers.

VICIdial download and VICIdial Web Client download

People often search for a VICIdial web client download, but agents have nothing to download. The client lives on the server, and agents just open its address.

What you do download is the server software. The usual route is the ViciBox ISO from the official VICIdial website. ViciBox is built on openSUSE and installs Asterisk, Apache, MariaDB and VICIdial together. The installer lets you choose a single all-in-one machine or separate roles for a cluster. When the install finishes, the client is live at /agc/vicidial.php.

Take the VICIdial download from the official site only. Copies from forums or file-sharing pages can be outdated or modified.

VICIdial agent login, step by step

The VICIdial agent login has two screens.

• Open the KingAsterisk Free Live Demo in Chrome or Firefox.
• Use the demo login credentials provided on the demo page to access the VICIdial Agent Login screen.
• Enter the required agent login details in the demo interface.
• Select an available campaign from the dropdown, if prompted.
• Click Submit and follow any browser microphone permission prompts if browser calling is enabled.

After login you land on the main screen in a paused state. Click Resume to start taking calls.

Agent web client: campaign login

The campaign dropdown only lists campaigns your user group is allowed to use. If yours is missing, ask your admin to check Allowed Campaigns on your user group under Admin > User Groups. Picking the wrong campaign is a common reason agents get no calls, so read the name before you click Submit.

You may also see this page called the agent web client 2.0 login. Layouts differ between builds and custom themes, so confirm the exact address with your administrator. The standard flow is the same: phone login, then user login and campaign.

VICIdial Web Client example: one call from start to finish

Here is a normal session in the VICIdial Web Client on an outbound campaign that uses ADAPT_TAPERED.

• The agent logs in and clicks Resume.
• The system dials leads in the background. When a person answers, the call drops into the agent’s browser phone and the lead’s name, phone number and city fill the screen.
• The Script tab shows what to say, with the lead’s first name already in place.
• The call ends. The agent clicks Hangup Customer, picks a status such as SALE, NI, NA, CALLBK or DNC, and submits it.
• The system moves on to the next lead.

Warm transfers use the Transfer – Conf button. Every status is saved with the lead, so supervisors can pull reports by agent, talk time and disposition, and reload leads by status later.

How to set up a VICIdial script

A VICIdial script is a block of HTML that shows up in the Script tab of the agent screen. You create it under Admin > Scripts and pick it in the campaign’s Script setting. Variables wrapped in –A– and –B– pull lead data into the text.

<p>Hello, may I speak with --A--first_name--B-- --A--last_name--B--?</p>
<p>This is --A--fullname--B-- from Your Company. Is --A--phone_number--B-- the best number to reach you?</p>

<p>Hello, may I speak with --A--first_name--B-- --A--last_name--B--?</p>
<p>This is --A--fullname--B-- from Your Company. Is --A--phone_number--B-- the best number to reach you?</p>

Keep scripts short. Agents glance at them during a call, so one clear opening line and a few branching notes work better than a full page of text.

Browser calling in the VICIdial Web Client

The browser phone uses WebRTC through ViciPhone, a JavaScript SIP client that runs inside the page. Four things have to be in place.

First, HTTPS with a certificate the browser trusts. Browsers block microphone access on plain HTTP pages, and a self-signed certificate usually makes the secure WebSocket connection fail. Let’s Encrypt works fine.

Second, the Asterisk WebSocket server turned on in /etc/asterisk/http.conf:

[general]
enabled=yes
bindaddr=0.0.0.0
bindport=8088
tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/letsencrypt/live/dialer.example.com/fullchain.pem
tlsprivatekey=/etc/letsencrypt/live/dialer.example.com/privkey.pem

[general]
enabled=yes
bindaddr=0.0.0.0
bindport=8088
tlsenable=yes
tlsbindaddr=0.0.0.0:8089
tlscertfile=/etc/letsencrypt/live/dialer.example.com/fullchain.pem
tlsprivatekey=/etc/letsencrypt/live/dialer.example.com/privkey.pem

Third, the phone entry is marked as a webphone. Under Admin > Phones, set Set As Webphone to Y for that extension.

Fourth, open firewall ports: TCP 443 for the client, TCP 8089 for secure WebSocket, and UDP 10000 to 20000 for audio, which is the default RTP range in rtp.conf. If the server sits behind NAT, also set externip and localnet in sip.conf and check the ICE settings.

Common problems and fixes

Most trouble with the VICIdial Web Client comes from a short list of causes.

Use a current Chrome or Firefox, keep extra extensions off agent machines, and avoid logging the same user in from two browsers at once. That alone prevents a lot of support tickets.

FAQs

Get help with your VICIdial setup

KingAsterisk Technology installs, tunes and supports VICIdial for contact center teams. If you want the VICIdial Web Client branded with your logo, connected to your CRM or fixed after an upgrade, send us your agent count, daily call volume and dialing countries. We will reply with a clear plan and estimate.

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.