VICIdial agent training playbook: calls, transfers and callbacks

01 / 13

What the Agent Screen Is and How the Day Starts

Fast answer: log in with your phone credentials first, then your user login and campaign, in that order. Wait for the screen to settle on PAUSED before you press Ready. Watch the status indicator, not the clock, because the whole screen runs on a one-second poll behind the scenes. When a predictive call is assigned to you, the customer is already connected the instant your screen changes, so greet them immediately. Save one disposition per call, schedule callbacks instead of guessing at a good time to call back, and always use the Logout control at the end of a shift — never just close the browser tab.

In plain language: an agent is the person logged into the VICIdial agent screen taking or making calls; a campaign is one outbound calling project — one list, one dial pace, and one set of dispositions — that an agent joins at login; a list is a named batch of leads loaded and worked together as a unit; a lead is one contact record: a phone number plus its call history and any custom fields; a disposition is the outcome code you save at the end of a call, such as a sale or a callback; the hopper is the pool of leads a campaign has already marked callable right now, waiting for the dialer or an agent to use them; an in-group is an inbound queue an agent registers for, separate from the outbound campaign described above; a channel is one call leg inside Asterisk — one side of one connection; a conference is the audio bridge, MeetMe on older builds or ConfBridge on newer ones, that holds you, the customer, and anyone else on the call at the same time.

Behind that layout sits a live state machine, not a normal web page. vicidial.php renders your screen once at login; after that, a background request to vdc_db_query.php polls the server roughly once every second for as long as you stay logged in. That one-second poll is what flips your status indicator, loads a new lead's details, and starts your talk timer the moment a call lands — the page is not refreshing, it is reporting.

• Status indicator, top bar: READY, PAUSED, INCALL, and a few other states.
• Customer panel, center: lead details and any custom fields your campaign uses.
• Call controls, right side: DIAL, HANGUP, TRANSFER, PARK CALL, and the CALLBACKS tab.
• Script or web form panel, bottom: whatever your campaign attached to this call.

02 / 13

Step 1 — Log In With Phone Credentials, Then User and Campaign

Two separate logins happen on the same screen, in a fixed order. First, your phone credentials — a phone login and a phone password — tell VICIdial which extension or webphone you are sitting at. Second, your VICIdial user login and password, plus the campaign you are joining, tell VICIdial who you are and what work you are allowed to receive. Submit both together, and the server checks them in that order: phone first, then user and campaign.

A successful login does two things you cannot see happen separately: it writes a live session row for you, and it connects your extension into a conference — the audio bridge Asterisk keeps ready for your seat. Until that conference is actually joined, nothing you click will reach a real customer, so give the page a few seconds after Submit instead of clicking it again.

Your very first status after login is PAUSED, not READY, no matter how quickly you logged in. That is deliberate: nobody wants a brand-new session grabbed by a live call before the agent has even seen the screen. You choose when to go Ready, in the next step.

• Enter the phone login and phone password first, exactly as issued.
• Enter the user login, user password, and campaign next, in the same submission.
• Wait for PAUSED to appear before doing anything else.
• If nothing happens after Submit, wait; do not resubmit the form.

SELECT user, status, conf_exten, extension, agent_log_idFROM vicidial_live_agentsWHERE user = '<AGENT_USER>';

03 / 13

Step 2 — Go Ready, Go Paused, and Use Pause Codes on Purpose

Your status lives in one column the whole system watches: READY means available for a call, PAUSED means unavailable on purpose, INCALL means on a live call, and a few other values — QUEUE, CLOSER, MQUEUE — cover a call being delivered, an inbound call you are handling, or a manual-dial queue state. Press Ready only when you mean it; a predictive dialer treats Ready as a promise that you can take the next call it hands you.

Pausing always asks why. Every pause code your campaign offers has three properties an administrator sets, not you: Billable, YES, NO, or HALF, for payroll; Mgr Approve, whether a manager has to sign off before the code is granted; and Time Limit, how many seconds you can sit in that code before the system flags it. A code with no explicit limit still defaults to sixty-five thousand seconds behind the scenes, about eighteen hours, so do not read the absence of a warning as permission to stay paused indefinitely.

Pick the code that actually matches what you are doing — break, lunch, training, a technical problem — rather than the first one in the list. Every pause you take is logged against your name, and a manager reviewing your first week can tell a self-chosen pause from one the system or an administrator forced on you, so guessing at codes leaves a worse record than a slow, correct choice.

• READY only when you can actually take the next call.
• PAUSED always needs a code — pick the one that matches the real reason.
• Ask before assuming a code needs manager approval; check, do not guess.
• A pause with no visible time limit is not a pause with no limit at all.

SELECT pause_code, pause_code_name, billable, time_limit, require_mgr_approvalFROM vicidial_pause_codesWHERE campaign_id = '<CAMPAIGN_ID>'ORDER BY pause_code;

04 / 13

Step 3 — Receive a Predictive Call: The Customer Is Already Live

Predictive dialing works backward from what a manual phone call feels like. The dialer has already called several numbers, already gotten an answer, and already decided this specific answered call is yours, before your screen shows you anything. The one-second poll running in the background is what notices your assignment and flips your status to INCALL — and the moment it does, the customer is not ringing, waiting, or about to answer. They are already on the line, and they already said hello.

That order matters more than almost anything else in this guide. Greet the customer the instant the screen changes, before you have finished reading their name. Every second you spend getting oriented is a second of silence a real person sits through after already picking up their phone, and in several countries that silence is itself regulated, not just rude.

Confirm the right lead loaded before you say anything you cannot take back. The customer panel should already show a name and phone number that match who is actually on the line; if it looks wrong, or blank, use a neutral greeting while you check, rather than guessing at a name.

• Assume the customer is already connected the moment your status changes — do not wait for a ring you will never hear.
• Say hello first; read the lead details second.
• If the on-screen lead looks wrong, greet neutrally and verify before using a name.

05 / 13

Manual Dialing: When You Choose the Number

Manual dialing flips who decides: instead of the predictive dialer assigning you an already-answered call, you select or look up a lead yourself and ask the system to place exactly one call. Behind the button, that single click reserves the lead, logs the attempt, and requests one origination — one real outbound call — from Asterisk. Nothing about that sequence is designed to be pressed twice.

If the screen appears to hang after you press Dial, resist the reflex to click it again. A second press before the first request has resolved does not cancel or replace the first attempt; it can start a second, entirely separate, real call to the same number. Stop, wait a few seconds, and if the screen still has not moved, ask your manager to check the live state before you touch anything else.

The same caution applies to any manual override fields your campaign exposes, such as a dial prefix or a call-time check. Those exist for genuine edge cases, not for working around a stuck screen; if manual dialing looks broken, treat it as a question for a manager, not a setting to change mid-call.

#!/usr/bin/env bash  set -euo pipefail   CNF="/etc/vicidial-readonly.cnf"  LEAD_ID='<LEAD_ID>'   mysql --defaults-extra-file="$CNF" -e "SELECT status, user FROM vicidial_list WHERE lead_id = $LEAD_ID;"   mysql --defaults-extra-file="$CNF" -e "SELECT user, status, callerid, lead_id FROM vicidial_live_agents WHERE lead_id = $LEAD_ID;"  

06 / 13

Save a Disposition: Close the Call the Right Way

A disposition is not a formality; it is the single action that ends the call's workflow and tells the rest of the system what actually happened. Saving one can update the lead, log the call, and, depending on how your campaign is configured, send an email, notify another system through a configured web address, or route the lead to quality control (QC) review before you ever move to the next screen.

Some disposition pairs exist specifically to separate what you decided from what the dialer decided automatically. An agent-classified answering machine and a dialer-classified one are different codes for a reason, and so are an agent-classified busy signal and a carrier-reported one. Mixing them up does not change what happened on the call, but it does quietly corrupt every report built on top of that code, weeks after you have forgotten which call it was.

A dial failure — a fast busy, a network reject, a number that never rings — is not the same disposition as a person who answered and then hung up on you. If you are not sure which code fits, ask before guessing; a wrong disposition on a real answer can incorrectly place a live lead onto a DNC (Do Not Call) list it never should have reached.

SELECT status, status_name, selectable, human_answered, scheduled_callback, dncFROM vicidial_campaign_statusesWHERE campaign_id = '<CAMPAIGN_ID>'ORDER BY status;

07 / 13

Scheduling a Callback: CALLBK vs. CBHOLD

CALLBK and CBHOLD are not the same thing, even though agents new to VICIdial use them interchangeably. CALLBK is the disposition you save when you tell the system to call this person back. CBHOLD is a state the lead itself sits in afterward, held out of normal dialing until the scheduled time you set actually arrives.

Saving a CALLBK also creates a separate scheduling row, not just a note on the call log. That row records whether the callback is USERONLY, reserved for you specifically, or ANYONE, meaning any agent in the campaign can take it once it is due. Your campaign's settings decide whether you can even see ANYONE callbacks from other campaigns, so do not assume your Callbacks tab shows every scheduled callback in the building; it shows the ones you are allowed to see, under this campaign's rules.

Treat the callback count on your screen and a historical CALLBK total on a report as two different numbers measuring two different things. One is what is currently scheduled and waiting; the other is how many calls, ever, ended with that disposition. A large gap between them is normal, not a sign either number is broken.

SELECT status, recipient, COUNT(*) AS callback_rowsFROM vicidial_callbacksWHERE campaign_id = '<CAMPAIGN_ID>'GROUP BY status, recipientORDER BY status, recipient;

08 / 13

Blind vs. Warm Transfer: Get the Right One

A blind transfer sends the customer straight to another destination and drops you from the call in the same motion. You never speak to whoever picks up on the other end; you go directly to your disposition screen the instant the transfer completes. Use it only when you are certain the destination is correct, because you will not be there to catch a mistake.

A warm transfer, sometimes called a consultative or attended transfer, keeps you on the line while a third party joins. You speak to that destination first, confirm they are the right destination and ready to take the call, and only then leave the conference so the customer and the destination continue without you.

Transfer and conference actions are stateful: each button press assumes one specific situation exists at that instant, and pressing the same button again does not simply repeat the first press safely. There is no rollback once you have left a call — if a warm transfer lands on the wrong destination, you cannot pull the customer back yourself; stop before you press anything twice, and check with a manager if the screen has not visibly changed.

• Blind transfer: instant, one-way, no rollback — confirm the destination before you press it.
• Warm transfer: verify the destination out loud, then leave the conference on purpose.
• Never press a transfer or conference button twice while waiting for the screen to update.

09 / 13

Three-Way Conference: Add a Third Party Without Losing the Customer

A three-way conference is the warm transfer's cousin: instead of leaving once the third party joins, you stay, and all three legs — you, the customer, and the third party — share the same conference at once. That third party might be a colleague answering a question, a supervisor confirming an approval, or an outside number the customer asked to include.

The three of you are sharing one Asterisk conference bridge, not three separate calls stitched together, so confirm your customer is comfortable with a third party joining before you start dialing them in, not after. If that third party is an automated menu instead of a person, you can send touch-tone digits, DTMF, short for dual-tone multi-frequency, into the same conference instead of speaking.

If the third party never picks up, or the conference looks stuck, do not repeatedly press whatever button started it. Each press is a separate, stateful action against a call that may already be mid-transition. Give it a moment, and if it is still wrong, ask a manager to check the actual conference state on the server rather than guessing from the screen.

#!/usr/bin/env bash  set -euo pipefail   CONF_EXTEN='<CONF_EXTEN>'   # This build's servers table sets conf_engine to ConfBridge:  asterisk -rx "confbridge list $CONF_EXTEN"   # Older VICIdial builds, or a server row still set to MeetMe, use this instead:  asterisk -rx "meetme list $CONF_EXTEN"  

010 / 13

Log Out Cleanly at the End of Shift

Logging out is its own action, not a side effect of closing your browser tab. The Logout control tells the server to end your session on purpose, coordinating three things at once: your browser session, your live-agent database row, and whatever the phone side needs to clean up on Asterisk. Closing the tab instead skips all three.

If you are mid-call when you log out, the system waits: your logout takes effect once you have saved a disposition, not before. If you are paused or ready with no call, it happens immediately. Either way, wait for the confirmation on screen before you walk away or shut down your machine.

A session left open by a closed tab does not vanish immediately. It can sit as a live row until a cleanup process notices it is stale, which means a seat that looks occupied, or a phone that looks busy, for longer than it should. If you ever have to step away without warning, log back in and out properly the moment you can, rather than leaving it for someone else to find.

• Always use the Logout control — never just close the tab.
• If mid-call, wait for your disposition to save before logout completes.
• Confirm the on-screen logout message before you walk away.

SELECT COUNT(*) AS live_rowsFROM vicidial_live_agentsWHERE user = '<AGENT_USER>';

011 / 13

Troubleshoot the First Week: Common Agent-Screen Problems

Most first-week problems trace back to the same handful of causes. Before assuming something is broken, check these against what you now know about the login order, the one-second poll, and pause codes.

The screen seems to freeze at disposition. This is usually the campaign's own wrap-up timer, a deliberate pause the system inserts after every call so you have time to finish notes before the next one lands, not a failure of the screen itself. Give it the full time before assuming it is stuck.

A pause code will not apply. Check whether it needs manager approval first; a code waiting on Mgr Approve looks unresponsive until someone actually grants it, which can take longer than a busy manager realizes.

A manual dial did nothing. Refer back to the manual-dialing section above: stop, do not press it again, and have a manager check the lead and live-agent rows before you touch the screen a second time.

• Wrap-up time at the end of a call looks like a freeze but is not one.
• A pause code pending Mgr Approve is waiting on a person, not broken.
• A manual dial that seems to hang needs a check, not a second click.
• When in doubt, ask before repeating an action the screen has not confirmed.

012 / 13

For Managers: What to Watch While an Agent Learns

Watching a new agent well means watching specific things, not just sitting nearby. Confirm the two-step login actually reaches PAUSED with a real conference before you leave them alone — a login that looks fine on screen but never joined the conference is the single most common early problem.

Watch their first few predictive calls in particular. The customer is live the instant the screen changes, and a new agent's instinct is to read the lead panel before speaking; coach the greeting-first habit in the first hour, not after a week of complaints.

Review pause activity, not just pause totals. The agent log records whether a pause was chosen by the agent, forced by the system, triggered through an integration, or set by an administrator, which tells you whether a trainee is over-using self-chosen pauses or simply hitting normal system wrap-up time. Use that distinction in coaching instead of guessing from a total-minutes number alone.

Spot-check dispositions against what you can independently confirm — a recording, a callback that actually shows up, a DNC entry that actually took. A trainee who is fast and confident but consistently wrong on disposition choice is a harder problem to catch than one who is slow.

• Confirm the login reached a real conference before leaving a new agent alone.
• Coach the greeting-first habit during the very first predictive calls.
• Read pause_type, not just pause totals, before coaching on breaks.
• Spot-check dispositions against something you can independently confirm.

SELECT pause_type, COUNT(*) AS pause_events, SUM(pause_sec) AS seconds_pausedFROM vicidial_agent_logWHERE user = '<AGENT_USER>'AND event_time >= CURDATE()GROUP BY pause_typeORDER BY seconds_paused DESC;

013 / 13

One-Page Agent Quick-Reference Card

Keep this next to your screen for the first few weeks. It does not replace the sections above — it is what to glance at mid-shift when you only have a few seconds to check something.

VICIDIAL AGENT QUICK REFERENCE LOGIN ORDER1. Phone login + phone password2. User login + password + campaign-> Status starts at PAUSED. You choose Ready. STATUS MEANINGSREADY   - available for the next callPAUSED  - unavailable, code requiredINCALL  - on a live callQUEUE   - a call is being delivered to you PREDICTIVE CALLSThe customer is ALREADY connected when yourscreen changes. Greet first, read second. MANUAL DIALINGOne click = one real call. If the screenseems stuck, stop. Do not click Dial again. DISPOSITIONPick the code that matches what actuallyhappened. Agent-classified and dialer-classifiedcodes are not interchangeable. CALLBACKCALLBK  = the disposition you choseCBHOLD  = the lead is now waiting, not dialable TRANSFERBlind = instant, no rollback, you leave nowWarm  = you verify, then leave on purpose 3-WAY / CONFERENCEEveryone hears everyone once they join.Never press a transfer or conference button twice. LOGOUTAlways use Logout. Never just close the tab.