Add AI transcription to VICIdial safely: a test-only call-recording workflow

Guided example: find the recording with recording_lookup before you touch a file

VICIdial ships its own tool for finding a recording: the Non-Agent API's `recording_lookup` function searches read-only by agent and date, or by a lead's numeric lead_id — see vicidial-non-agent-api-guide for the full function list, its permission model and how to set up the credential file. The account you use for it needs user_level 7 or higher and "view reports" enabled; confirm or create that account with your VICIdial administrator before your first request.

That lookup exists because the recording itself is not in one predictable place: on our ViciBox 12 lab, a campaign's recording extension runs Asterisk's `Monitor()` application, and a separate cron job later mixes the two call legs and moves the finished files into format and stage subfolders. `recording_lookup` hides that internal layout instead of asking you to reconstruct it, which is why it is the first step here, not a last resort.

A transcription workflow built on top of that lookup is still a much smaller change than letting a bot answer or place calls: a worker copies one approved recording, sends it to a speech-to-text API, and places the result in a review queue. Start here so the team can validate accuracy, privacy, retention and identifiers before any live media design.

A fresh lab with no completed test calls yet is expected to return a NO RECORDINGS FOUND line, not a fault in your request. Treat that response as the correct baseline and place at least one completed, consented test call through your disposable campaign (see vicidial-first-agent-call if you have not placed one yet) before concluding the lookup is broken.

recording_lookup also accepts uniqueid and extension as alternate search fields alongside agent and date, and a duration=Y setting that adds each recording's length in seconds ahead of its location — useful context to log in your manifest without needing the file itself.

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=recording_lookup" \  --data-urlencode "agent_user=<AGENT_USER>" \  --data-urlencode "date=<YYYY-MM-DD>" \  --data-urlencode "header=YES"

Use one stable identifier and a written data boundary

Pick one non-secret correlation value already allowed by your lab—such as an internal test call ID—and store it beside every job. Do not use a phone number as the job key. The worker needs a small manifest: recording path, checksum, internal call ID, consent flag, creation time and retention deadline.

A transcript is derived customer data, not harmless debug text. Decide who can read it, where it is stored, how long it lasts, and how deletion reaches both the audio and downstream transcript before the first upload.

Guided example: inventory an already-exported copy (fallback)

If you are working from an already-exported copy of what `recording_lookup` reported, rather than calling the API directly for this exercise, this command lists only WAV files in a dedicated lab export directory and calculates a checksum. It does not contact an AI provider or change Asterisk, and it is a fallback step, not the first place to look.

Point this only at a dedicated export directory you control, never at Asterisk's own recording tree. If you need to confirm that a stage folder exists there, list the directory itself, never its contents, and let recording_lookup or your recording owner supply the actual file.

LAB_AUDIO=/srv/vicigeek-lab/audiofind "$LAB_AUDIO" -maxdepth 1 -type f -name '*.wav' -printf '%f\n'sha256sum "$LAB_AUDIO/test-call-001.wav"

Guided example: submit one approved file for transcription

The provider endpoint and model below are an example of a documented audio-transcription API. Keep the API key in an environment variable supplied by a secret manager; never put it in a VICIdial campaign, browser page, shell history, article screenshot or source control.

The response is evidence for review, not a disposition and not an automatic update to a lead. A transcript can contain recognition errors and must not change customer or agent records without a person-approved rule.

export TRANSCRIPTION_API_KEY='set-this-through-your-secret-manager'curl --fail-with-body https://api.openai.com/v1/audio/transcriptions \  -H "Authorization: Bearer $TRANSCRIPTION_API_KEY" \  -F file=@/srv/vicigeek-lab/audio/test-call-001.wav \  -F model=gpt-4o-transcribe \  -o /srv/vicigeek-lab/output/test-call-001.json

Review accuracy before you build automation

Compare the transcript with the known lab script. Record omissions, incorrect names, speaker confusion and timestamps that matter to the intended use. If you need speaker labels, test that as a separate acceptance criterion; do not assume that a transcript identifies agent and customer correctly.

Do not score agents, infer eligibility, or trigger customer actions from the first experiment. A human reviewer should approve any structured fields before they are written to a CRM or report.

Only then assess a live voice-bot design

A real-time bot needs its own routing, interruption, escalation to a human, DTMF, recording, disclosure, outage and fallback decisions. Asterisk ARI can manipulate media and emits events over a WebSocket, but whether it fits a particular VICIdial build is an architecture question to test in a separate isolated environment.

Keep the initial production candidate asynchronous: completed recording to bounded review queue. It avoids making call completion depend on an external AI service and gives the team a clean stop switch: disable the worker while VICIdial and Asterisk continue their normal call flow.

• The recording was synthetic and consented.
• The transcript has an internal ID and deletion/retention owner.
• A reviewer checked it before any system-of-record update.