VICIdial agent-only callbacks: keep follow-ups with the right agent

01 / 08

A callback is a promised follow-up

A scheduled callback is a future task connected to a lead. VICIdial supports two different recipients: USERONLY means the agent who created it owns the task; ANYONE means a suitably available agent in the campaign can handle it. Choose the recipient before worrying about timing.

This is a workflow choice, not a minor label. VICIdial's own feature list describes both agent-only and anyone callbacks, and the agent screen is where people carry out the work.

02 / 08

USERONLY is not a hopper entry

VICIdial ships its own definition of the holding status a callback sits in before it is due. VICIDIAL_statuses.txt defines CBHOLD as "Call Back Hold - Scheduled ANYONE callback that has not hit it's trigger, or an AGENTONLY callback." In plain language, both kinds of callback wait in that same status; when an ANYONE callback's time arrives, it moves into the hopper (the short list of leads a campaign is about to dial next) for whichever agent is available. A USERONLY callback never makes that move — it stays assigned to the agent who owns it, and only that agent can select it. A VICIdial forum thread reports the same split in day-to-day practice.

That means a team wanting an automatic agent-specific dial needs a reviewed custom workflow, not a database trick. For a noob-friendly default, let the owner select the callback in the Agent screen and make the call deliberately.

03 / 08

What the record looks like end to end

VICIdial's own docs are not perfectly consistent about the agent-only recipient's name: VICIDIAL_statuses.txt's prose calls it an "AGENTONLY callback," while the Non-Agent API's lead_callback_info function reports the same thing in a real field that literally reads USERONLY. Both are shipped and citable; treat them as two names for one recipient, not a contradiction that needs resolving.

lead_callback_info's own example row shows two state values directly: callback_type ARCHIVE and callback_status INACTIVE, for a callback that has already been resolved. The same function's search_location field names CURRENT as the other callback_type value, for callbacks still in the active schedule; the doc never spells out callback_status's full value list, so treat ACTIVE as the expected-but-unconfirmed counterpart to INACTIVE and confirm it against a real pending callback on your own build. One more wrinkle: this output's callback_type field name is reused elsewhere in the API as an add_lead/update_lead input meaning USERONLY or ANYONE instead — same name, unrelated value set. Confirm the underlying table's real columns yourself before writing a query against it, rather than trusting an old forum post's column names.

SHOW COLUMNS FROM vicidial_callbacks;

04 / 08

Give the test agent only the needed access

In Users, review the test user rather than copying a production user. The relevant permission is Agent-Only Callbacks; some workflows also require Agent Call Manual so the agent can actually place the follow-up. User groups and campaign access still matter.

Do not grant broad administrator rights just to test callbacks. If the expected control is absent, record the VICIdial version, user group and campaign and ask the system owner to review the build-specific settings.

• Confirm the account is a synthetic test agent.
• Confirm the test campaign is the only campaign in scope.
• Confirm the agent knows the callback is a manual follow-up.

05 / 08

Guided example: schedule one agent-only test callback

Log in as the test agent, open the synthetic lead, choose the campaign's approved callback disposition, and select the agent-only recipient option. Set a time a few minutes ahead in the server/campaign timezone and write a harmless note such as 'LAB CALLBACK — do not call customer'.

Do not use a real contact merely to make a callback appear. A safe test uses a number owned by the lab or no dialing at all until an authorized test endpoint is ready.

Lead: <LEAD_ID>Recipient: USERONLYOwner: <AGENT_USER>Time: <SERVER_TIME + 5 MINUTES>Comment: LAB CALLBACK — test only

06 / 08

Guided example: take it and verify the outcome

At the scheduled time, keep the same test agent logged in and select the callback from that agent's callback area. Verify the lead and comment before manually dialing an authorized lab endpoint. End and disposition the lab call normally.

If the callback does not appear, first compare server time, campaign access and the agent-only permission. Do not reset the hopper: it is the wrong mechanism for USERONLY work.

SELECT status, recipient, user, callback_timeFROM vicidial_callbacksWHERE lead_id = '<LEAD_ID>'ORDER BY callback_time DESCLIMIT 3;

07 / 08

Confirm it a second way with the Non-Agent API

The Agent screen and the database agree once you have checked both; a third, independent confirmation is the Non-Agent API's lead_callback_info function, covered in full in vicidial-non-agent-api-guide. It needs only the lead's numeric lead_id, the same one used in the database check above.

Call it exactly like every other read-only Non-Agent API sample in this library: through the /etc/vicidial-api/readonly.cfg config file, over strict HTTPS, never with a password on the command line. Check that the API itself answers before trusting a callback-specific result — a version call first confirms the credential file, host and the account's api_allowed_functions list are all correct.

curl --fail-with-body --silent --show-error --config /etc/vicidial-api/readonly.cfg --data-urlencode "function=version" curl --fail-with-body --silent --show-error --config /etc/vicidial-api/readonly.cfg --data-urlencode "function=lead_callback_info" --data-urlencode "lead_id=<LEAD_ID>" --data-urlencode "search_location=ALL" --data-urlencode "header=YES"

08 / 08

Choose the right callback type next time

Use USERONLY when continuity with the same agent matters and that agent will select the follow-up. Use ANYONE when the service promise is that the next qualified agent may handle it. Document the rule in the campaign script so agents do not guess.

If an owner leaves or coverage changes, have an authorized administrator follow the organisation's change process. Avoid bulk direct database edits: they bypass the UI's normal workflow and make audits harder.

• I can say why USERONLY does not enter the shared hopper.
• I tested only a synthetic callback.
• I know who owns changes to callback permissions and coverage.