VICIdial inbound call handling: the complete guide

VICIdial inbound call handling: the complete guide

flowchart TD
    A[Inbound call hits DID] --> B{Call menu IVR?}
    B -->|Yes| C[Route by keypress]
    B -->|No| D[Send to in-group]
    C --> D
    D --> E{Within Call Time?}
    E -->|No| F[After Hours Action]
    E -->|Yes| G{Agent available?}
    G -->|Yes| H[Connect to agent]
    G -->|No| I[Hold music and place-in-line]
    I --> J{Wait too long?}
    J -->|Yes| K[In-queue callback or overflow]
    J -->|No| H

Most people meet VICIdial as an outbound dialer, but it handles incoming calls just as well. When a customer dials one of your numbers, VICIdial has to answer the line, figure out where the call belongs, hold the caller while it finds someone to talk to them, and finally connect them to a live Agent. This guide walks through every piece of that journey in plain terms, so you can set up inbound calling without guessing at which field does what. If you would rather skip the self-hosted setup entirely, our managed plans hand you a working box in under a minute.

We will start with the building block everything else rests on, the in-group, then follow a single call from the moment it rings to the moment an agent picks up. Along the way we cover the friendlier features your callers actually notice, hold music, place-in-line announcements, and callbacks, and the safety nets that catch calls when nobody is around to answer them.

In-groups: where inbound calls live

An Ingroup is a queue. It is the container that holds incoming calls and decides which agent gets the next one. Nothing reaches a person without passing through an in-group first, so this is always step one. If you want the short version before diving in, read what an inbound group actually is. A common point of confusion is the difference between this and an outbound campaign, which we untangle in in-group versus campaign.

To make a queue, open the Inbound section and add a new in-group. You give it a short ID (letters, numbers, and underscores only, between two and twenty characters) and a name. The ID is permanent, so pick something you will recognize later like SALES or SUPPORT. The full walkthrough is in adding a new inbound group. A fresh in-group will not show up in the agent login box until you set it Active and allow it in at least one campaign, and you can give it a color so agents can tell at a glance which queue a ringing call came from.

The most important routing decision is the Next Agent Call method, which controls who out of your available agents receives the incoming call. You can spread calls evenly so everyone takes a fair share, send the next call to whoever has been waiting longest, or weight calls toward your stronger people using the next-agent options. If you prefer to lean on rank and grade rather than wait time, the search method and per-agent rank and grade controls let you do exactly that. When you run several queues at once, the queue priority setting decides which queue's callers jump ahead. There is also a fronter display option so a closer can see the name of the fronting agent who transferred a call across.

What the caller hears: welcome, hold, and place in line

Once a call lands in the queue, the first thing it can do is play a greeting. The welcome message is an audio file that runs when the call arrives. One thing trips people up: the caller does not enter the queue to reach an agent until the welcome message finishes playing. If your queue is busy and you want callers connected the instant an agent frees up, it is often better to fold any greeting into the start of your hold audio instead.

While the caller waits, VICIdial plays Music on hold. You point the in-group at a music-on-hold context and it loops until an agent is ready. There is a separate on-hold prompt that interrupts the music every so often to play a short message, but be careful: while that prompt plays the caller cannot be connected to a free agent, so keep it brief or turn on its no-block option.

Two touches make a queue feel less like a black hole. The place-in-line feature tells callers they are, say, third in line and then announces when they move up to first. The estimated hold time feature reads back roughly how long the wait will be. You control when that estimate is calculated so it is not announced the instant a call arrives. Both are off by default, and both go a long way toward keeping people from hanging up.

Overflow and wait-time routing

Sometimes the wait drags on and you would rather give the caller a way out than make them sit in silence. The wait-time option watches how long someone has been in the queue and, past a threshold you set, plays a prompt offering them a choice: press 1 to leave a voicemail, press 2 to go to another menu, and so on. You can wire up to three different key presses. A close cousin, the hold-time option, triggers off the estimated wait rather than time already spent waiting, which is handy when you can see a long queue forming before anyone has actually waited that long.

For higher-volume queues you can also escalate. The overflow and escalation controls let waiting calls spill into another in-group, and the agent-alert sounds can grow more insistent the longer a repeat caller has been trying to reach you. Used together, these keep a sudden rush from turning into a wall of abandoned calls.

In-queue callback: hold the spot, drop the wait

The single feature callers appreciate most is the In-queue callback. Instead of waiting on hold, the caller keeps their place in line and hangs up, and VICIdial calls them back the moment their spot reaches the front. The full setup lives in the in-queue callback guide, and if you want the variant that builds a separate callback queue rather than holding the line position, see the virtual queue callback.

A few details matter here. You can have the system confirm or correct the number to call back, covered in caller-ID callback validation, so you do not waste a callback on a spoofed or malformed CID (caller ID). And because a held callback should not sit forever, the callback queue expire setting drops stale entries after a number of hours you choose.

After-hours and closing-time handling

Every in-group is tied to a Call times scheme that defines when you are open, and you assign that schedule through the in-group call time setting. When a call comes in outside those hours, the after-hours action takes over: you can play a closed message, send the call to voicemail, route it to another menu, or simply hang up.

There is a subtler case too. A call can arrive while you are still open but sit in the queue until you close. The closing-time action decides what happens to those stragglers when the day ends, and the closing-time now trigger lets you clear the queue early, for instance to send everyone still waiting to a callback so your agents can log off on time.

No-agent handling: when nobody is logged in

By default, calls will pile up in a queue even if not a single agent is logged in, which means callers wait for someone who is never coming. To prevent that, the no-agent no-queue setting stops new calls from entering an empty queue and routes them somewhere useful instead, a message, a voicemail box, or another in-group. You can tune whether paused agents count as present.

That check has a companion that runs continuously: the in-queue no-agents check pulls callers out of the queue if every agent logs off mid-wait. Two more guardrails worth knowing are the max calls cap, which limits how many calls a queue will hold at once, and the drop-call seconds limit, which decides how long a caller can wait before the call is counted as a Abandoned call and sent to a drop action. An agent alert sound and its escalating versions round out the noticing-something-is-wrong side of the queue.

DIDs: the phone numbers that feed your queues

A DID (direct inward dialing) is simply a phone number your carrier directs at your system. Until you tell VICIdial what to do with an incoming number, the call has nowhere to land. A DID entry is the routing rule for one number. Start with what a DID is and then adding a DID. There is a handy reserved -default- DID that catches any number that does not match a specific rule, so nothing slips through unrouted.

The key field on a DID is its route. You can point it at an in-group so the number rings your queue, send it straight to a named agent, or drop it into a call menu for press-1-for-sales style routing. The full set of route options also covers voicemail and raw dialplan extensions. When you route to an in-group, the handle method controls whether each call creates a new Lead or looks up an existing one by caller ID.

Call menus: building an IVR

A call menu is VICIdial's IVR (interactive voice response), the press-1-for-sales, press-2-for-support tree callers navigate before they reach a queue. Each menu plays a prompt, waits a set number of seconds for a key press, and then sends the call wherever the matching option points. The basics are in what a call menu is and adding one.

Because a menu option can route to another menu, you can chain them into multi-level menus, and once a menu is built you attach it to a number by pointing a DID at the menu. The usual flow is number, then menu, then in-group, with each option that picks the in-group route configured to feed the right queue.

Filter phone groups: routing by who is calling

Sometimes you want to treat callers differently based on their number rather than the number they dialed. A Filter phone group is just a list of phone numbers, and when a DID is set to filter against a group, any incoming caller ID that matches gets routed to a special destination. Learn the concept in what a filter phone group is and the mechanics in creating one.

The two everyday uses are opposites of each other. You can fast-track VIP callers to a priority queue, or you can block known nuisance numbers before they ever reach an agent. Building the list is the same in both cases, you just choose where matches go.

When inbound calls go wrong

Inbound problems almost always come down to a routing gap somewhere in the chain we just walked through. If calls are not reaching agents, check that the in-group is active, allowed in the campaign, and that agents have actually selected it. If a DID is not routing at all, confirm the carrier is sending the number in the exact format your DID pattern expects.

If callers get stuck on hold forever, the usual culprit is a no-agent setting that is letting calls queue with nobody to take them, or a too-generous drop-seconds limit. And if an IVR keypress does nothing, the option value in the menu probably does not match the key the caller is pressing, or a welcome prompt is swallowing the digit before the menu listens for it.

Putting it together

Inbound handling in VICIdial is really one pipeline: a DID catches the number, an optional call menu sorts the caller, an in-group queues them with hold music and place-in-line, callbacks and overflow give them an exit if the wait runs long, after-hours and no-agent rules catch anything that arrives when you are closed or empty, and filter phone groups bend the rules for specific callers. Set those pieces up once in that order and the whole thing runs itself.

Build it slowly: one in-group, one DID pointed at it, a couple of agents logged in, and a test call. Once that works end to end, layer on the niceties. If you would rather not stand up and secure the server yourself, every VICIfast plan ships a hardened box with inbound ready to configure in under a minute.

Frequently asked questions