VICIdial inbound callback queue: let callers leave hold and keep their place

01 / 10

Start here: a place in line, not an appointment

An in-group is the waiting room for incoming calls. With a queue callback, the caller chooses to leave hold while keeping a position in that waiting room. VICIdial later tries the return call when the queue position reaches an agent, subject to calling-time, expiry and filtering rules.

This is different from an agent scheduling a callback for a chosen time. It is also different from the separate abandoned-call recovery feature. Use the correct feature name when asking an administrator for help.

You should seeVerified in the isolated internal lab: caller choice → LIVE queue entry → SENT return call → agent handoff. Check the prerequisites and limits below before planning your own test.

02 / 10

1. Follow the call before changing settings

Trace DID → call menu if present → in-group → campaign and agent. A DID is the incoming entry route. If the caller reaches another group, settings on your intended group will not help. Choose one callback trigger for the lab: wait time, estimated hold time or closing time.

1. Confirm the incoming route ends at the intended lab in-group.
2. Confirm the agent is allowed to take that in-group through the selected campaign.
3. Identify the exact point where the caller should hear the callback choice.

You should seeYou can name the entry route, queue, campaign and expected callback prompt before testing.

03 / 10

2. Inspect the campaign and in-group together

Open the pages to inspect their saved values. Do not submit changes while taking the baseline. A prompt alone is not sufficient: the receiving campaign must permit the callback handoff.

Our installed revision-4037 code exposed an extra prerequisite: plain MANUAL mode is not eligible for this inbound callback handoff. For the controlled manual-calling lab we used INBOUND_MAN, enabled Allow Inbound and Blended, and selected only the lab in-group for both campaign and user. Ordinary list autodialing stayed off; the callback dispatcher intentionally made the return call. Do not switch a working production campaign to a predictive dial method for this test.

1. In a separately approved manual-calling lab, open Campaigns → your test campaign → Detail. Use Dial Method INBOUND_MAN and Allow Inbound and Blended Y so inbound group selection is available. Keep the test isolated to internal destinations.
2. Under Allowed Inbound Groups select only the lab group. The Transfer Groups list is separate; selecting a transfer group alone does not grant inbound queue membership.
3. In-Group Manual Dial must also be MANUAL_DIAL or BOTH; our lab used BOTH. Check that the test user is allowed the same group.
4. Open Inbound → In-Groups → your lab group. Find the wait-time, estimated-hold-time or closing-time option you intend to use; its callback choice is PRESS_CALLBACK_QUEUE.
5. Find Callback Queue Expire Hours, Callback Queue Call Time and Callback Queue Dial Filter. Record the values, including which DNC lists the filter checks.
6. If using the closing-time route, inspect its Press and End audio filenames. The source limits the Closing Time Press prompt to ten seconds or less.
7. Leave Closing Time Now Trigger unchanged. It is an action affecting waiting calls, not a harmless preview button.
8. At the Agent screen open GROUPS, move only the lab group into Selected Groups, and submit. For INBOUND_MAN the Blended option stays off. Verify the selected group in the real agent session, not just the saved administrator forms.

You should seeThe campaign accepts the handoff and the in-group has a specific callback offer plus a calling-time, filter and expiry policy.

04 / 10

3. Check the conditions for a return call

DNC means do not call. The configured filter and calling window still apply to a queue callback. A request alone does not remove those gates.

05 / 10

4. Inspect the installed queue without creating a call

An administrator can inspect the schema through a read-only session before choosing a narrow query for the approved synthetic fixture. Do not paste an INSERT from a tutorial into a queue table: the background worker may pick it up and initiate a call.

SHOW TABLES LIKE 'vicidial_inbound_callback_queue%';SHOW COLUMNS FROM vicidial_inbound_callback_queue;

06 / 10

5. Rehearse the decision with fictional entries

All seven local checklist cases passed using fictional entries and no server connection. This exercise rehearses evidence decisions; it neither reproduces the queue scheduler nor creates real queue statuses. Ready means suitable for a controlled dispatch test, not a placed, answered or connected call.

07 / 10

6. Practical checks and their limits

On November 7, 2026, an authenticated synthetic PJSIP caller reached the test in-group. We started the caller’s looping RTP source, waited for the actual to-be-called-back offer to accept digit 1, and then sent one digit on that caller’s channel. Queue row 1 became LIVE. This checks the caller’s choice and queue admission, not merely that an AMI action was accepted.

After that caller left hold, we made its internal return endpoint available and resumed the test agent. The queue row became SENT. We also verified the return PJSIP leg was Up, the native Agent session was INCALL on the queued lead, and agent and customer profiles shared the same ConfBridge room. These checks establish the observed internal handoff; SENT alone would not.

The first Local-channel simulation had been rejected by the installed inbound AGI guard. A second attempt sent its digit before the offer and later stopped because it sent no RTP. The corrected test fixed those harness problems and kept the vendor guard intact. A fixed sleep after answer is not a reliable way to choose this callback.

We dispositioned the call HUNGUP and logged out. The full lab used all 10 approved internal dial attempts. Original campaign and system settings were restored; owned fixtures were disabled and temporary routes removed. The final PBX check showed zero active calls and channels. Call and recording history was preserved.

Expiry, DNC rejection, no-answer recovery and ORPHAN recovery were not exercised live. No runtime callback screenshot was captured. External carrier routing, production capacity and human listening quality are outside this synthetic test.

The callback-offer settings in the native form

Open to enlarge

You should seeThe scoped caller-choice → queue-entry → return-call → agent-handoff test passed. It proves this internal path and configuration, with the limits above.

Download the final callback and restoration receipt →

Download all six dated practical results and limits →

08 / 10

7. Prepare the complete internal test

Acceptance starts with the caller entering the queue and ends with the observed return attempt and agent handoff. Use an approved synthetic caller and isolated internal destination, with no carrier route.

1. Record the original settings and verify the internal route, final dial string, existing prompt files, callback window, expiry and DNC expectation. A configured audio filename is not proof the file exists; our new lab group had a missing default end prompt, which we replaced with an existing lab prompt.
2. Check number composition explicitly. In our internal fixture the stored number was 9001103 and phone code was 1, producing only the reviewed internal extension 19001103. Prefixes and list overrides can change this; do not assume the system will strip a country code from every short test number.
3. Use a real supported test-phone channel for the incoming call, and keep its RTP active. On the inspected build a normal inbound AGI rejects a Local-channel simulation; do not remove that vendor guard to force a test through.
4. Press 1 once when the callback offer actually asks for it. A fixed delay after answer is insufficient: welcome and hold audio can come first. Our early scripted press was received but did not create a queue entry.
5. Verify the caller leaves hold and one matching synthetic queue entry appears in LIVE state.
6. Observe the Real-Time report’s Callback Queue Calls indicator and SHOW IN-GROUP STATS. Record the entry’s state and time without exposing the caller’s number.
7. Make the designated lab agent available. Verify the return attempt reaches only the internal destination and the answer is handed to that agent.
8. Record the terminal queue state and the corresponding call history. A status alone is not evidence of intelligible audio; check that separately if it is in scope.

You should seeMark the end-to-end callback verified only when the caller choice, queue entry, return attempt and agent connection are all observed.

09 / 10

8. Read the state before trying again

An administrator should check the existing AST_VDadapt.pl worker and logs. Do not start a second copy as a repair. Keep the in-group ID, timestamp and synthetic identifier together when reporting a problem.

10 / 10

9. Restore the fixture and prevent duplicate attempts

If any step produces an unexpected destination or uncertain call state, stop the test. Do not reset an ORPHAN or SENDING entry to LIVE by hand. First reconcile the actual call history so a caller is not dialed twice.

1. End only the approved lab calls and restore agent availability through the application.
2. Restore the campaign, in-group and routing values changed for the test, then confirm the saved values.
3. Use supported application controls to retire the synthetic fixture after checking there is no pending return attempt. Keep the queue and call evidence; do not delete runtime rows as cleanup.
4. Record whether the test reached each checkpoint or stopped at a named missing prerequisite.

• Caller chose the callback
• One intended queue entry observed
• Return attempt reached only the internal route
• Agent handoff and final state reconciled, or the evidence gap remains explicit