IVR-driven verification surveys with agi-IVR_recording_verification.agi

Third-party verification (TPV) is the process of recording a customer's spoken or DTMF consent to an order or agreement, handled by a party that is independent of the sales agent who took the order. In call center environments, this is usually done by transferring the customer to a dedicated IVR (interactive voice response) that walks through a scripted set of yes/no questions and records the entire interaction.

VICIdial ships a complete AGI (Asterisk Gateway Interface) script for exactly this use case: agi-IVR_recording_verification.agi. It handles the full verification session autonomously - optional company and customer code collection, date announcement, a sequence of prompt-and-response steps, and a final Call recording that captures the entire exchange. All session data logs to the vicidial_ivr table.

How the IVR verification flow runs

flowchart TD
  A[Call Arrives at Exten] --> B[Play welcome prompt]
  B --> C{Ask company code?}
  C -->|Y| D[Collect company digits]
  C -->|N| E{Ask user code?}
  D --> E
  E -->|Y| F[Collect user digits]
  E -->|N| G{Ask phone number?}
  F --> G
  G -->|Y| H[Collect phone digits]
  G -->|N| I[Speak date if enabled]
  H --> I
  I --> J[Play prompt sequence and collect single digit per step]
  J --> K[Play recording ID prompt]
  K --> L[Log to vicidial_ivr]
  L --> M[Hangup]

Each step in the prompt sequence expects a single digit key press. Only digits 1 through 9 are accepted - hash, pound, star, and zero are all rejected at every question step. This constraint is intentional: it prevents accidental disconnects (which often map to * in some telecom systems) from being recorded as valid responses.

Argument structure and dialplan entry

The argument string is long and dash-delimited. Each segment maps to a specific feature: the DNIS or inbound number called, whether to play the recording ID (Y/N with a prompt filename), whether to Call recording the call, whether to ask for a company code with its digit count and prompt filename, whether to ask for a user code, whether to ask for the customer's phone number with digit count and prompt, whether to speak the current date, a dash-delimited list of prompt filenames that expect responses, the final recording-ID announcement prompt, and the logging mode (FILE, STDERR, BOTH, or NONE).

; Inbound IVR call
exten => 1234,1,Ringing
exten => 1234,2,Wait(1)
exten => 1234,3,Answer
exten => 1234,4,AGI(agi-IVR_recording_verification.agi,7274506620---Y-85100004---Y---Y-1-85100016---N---N---Y-85100007---85100009-600--85100012-30--85100013---85100004---BOTH)
exten => 1234,5,Hangup

; Inbound from a VICIDIAL transfer
exten => _83002*.,1,Ringing
exten => _83002*.,2,Wait(1)
exten => _83002*.,3,Answer
exten => _83002*.,4,AGI(agi-IVR_recording_verification.agi,7275551234---N---Y---N---N---Y-10-85100001---N---85100002-85100003---85100004---BOTH)
exten => _83002*.,5,Hangup

The prompt filenames - 85100001, 85100002, and so on - are 8-digit sound files in /var/lib/asterisk/sounds. You create these files using agi-record_prompts.agi or by placing pre-recorded GSM files there directly. The script also references several named files by convention: ld_welcome_pin_number for the welcome greeting and auth-thankyou for the closing confirmation.

Logging and outbound survey use

Session data goes to the vicidial_ivr table and optionally to a flat log file or STDERR on the Asterisk process, depending on the logging argument. The script reads database connection settings and the log file path from /etc/astguiclient.conf. It does not use any other configuration file.

The Recording delay between the welcome prompt and the first question step can be tuned using the prompt timeout values embedded in the prompt list argument. Each prompt entry can carry an optional timeout in seconds after its filename, which controls how long the script waits for a DTMF digit before advancing or retrying.

For the broader context of AGI tools in VICIdial, see the VICIdial API and AGI overview. If you need to secure the API endpoint that transfers calls into this IVR, the API security guide covers the access controls involved.

Every VICIfast plan provisions a ready-to-configure VICIdial instance in under 40 seconds, so you can wire up your verification IVR without spending time on the underlying server setup.