Build Production-Grade ViciDial IVR Systems with Asterisk and Database-Driven Logic

ViciDial IVR Setup with Asterisk — Inbound Call Menus

ViciDial’s IVR architecture integrates Asterisk dialplans with a backend database to maintain persistent call states across the agent lifecycle. The system requires Asterisk 13+ compiled with res_agi and MariaDB to handle production-grade inbound call flows. This setup enables features like real-time logging, agent integration, and automated call recording within the IVR.

Why This Matters

Traditional Asterisk IVRs often rely on static configuration files, which create significant management overhead for high-volume call centers with frequently changing business rules. By migrating menu logic into a relational database and using AGI scripts for routing, engineers can implement dynamic menus that scale without requiring constant dialplan reloads. This approach ensures that call metadata is captured in the vicidial_log table, providing the necessary data for compliance, reporting, and agent-side integration that standard IVRs lack.

Key Insights

• ViciDial IVR requires specific audio formatting: 8-bit, 8000 Hz mono WAV files are mandatory for stable playback.
• The VICIDIAL_log_insert.agi script must be called at the IVR entry point to ensure call metadata is properly logged to the database.
• Dynamic routing is achieved by storing menu configurations in custom tables like vicidial_ivr_menus and vicidial_ivr_options.
• DTMF input failures are commonly caused by mode mismatches; ViciDial typically requires dtmfmode=rfc2833 in the SIP configuration.
• Priority routing can be implemented by setting the QUEUE_PRIORITY variable before the call enters the Asterisk Queue function.
• Call recording in the IVR phase requires explicit MixMonitor setup and proper directory permissions on /var/spool/asterisk/monolithic/recordings/ivr.

Working Examples

Core IVR dialplan structure for ViciDial entry and basic menu routing.

[from-vicidial-ivr]
exten => s,1,Answer()
exten => s,n,Set(CALLFILENAME=${UNIQUEID})
exten => s,n,Set(CHANNEL(language)=en)
exten => s,n,NoOp(=== ViciDial IVR Entry ===)
exten => s,n,Set(vicidial_log_id=${SHELL(/usr/share/astguiclient/VICIDIAL_log_insert.agi ${CHANNEL(name)} ${EXTEN} ${CALLERID(num)} ${CALLERID(name)})})
exten => s,n,Goto(ivr_main_menu,s,1)

[ivr_main_menu]
exten => s,1,NoOp(=== Main Menu ===)
exten => s,n,Set(TIMEOUT(digit)=5)
exten => s,n,Set(TIMEOUT(response)=10)
exten => s,n,Background(/var/spool/asterisk/monolithic/recordings/main_menu_prompt)
exten => s,n,WaitExten(2)

exten => 1,1,Goto(sales_queue,s,1)
exten => 2,1,Goto(support_queue,s,1)
exten => 0,1,Goto(operator_queue,s,1)

Schema for implementing database-driven dynamic IVR menus.

CREATE TABLE vicidial_ivr_menus (
  menu_id INT AUTO_INCREMENT PRIMARY KEY,
  menu_name VARCHAR(50) UNIQUE NOT NULL,
  campaign_id VARCHAR(20),
  prompt_filename VARCHAR(255),
  timeout_seconds INT DEFAULT 10,
  active INT DEFAULT 1
) ENGINE=InnoDB;

CREATE TABLE vicidial_ivr_options (
  option_id INT AUTO_INCREMENT PRIMARY KEY,
  menu_id INT NOT NULL,
  digit_pressed VARCHAR(2),
  action_type ENUM('goto_menu', 'queue', 'voicemail', 'hangup', 'agi_script'),
  action_target VARCHAR(100),
  FOREIGN KEY (menu_id) REFERENCES vicidial_ivr_menus(menu_id)
) ENGINE=InnoDB;

Practical Applications

• Dynamic Account Validation: Implement a ‘Read’ function in the dialplan to capture DTMF account numbers and validate them against a CRM via AGI before routing to specialized queues.
• Pitfall: DTMF Mode Mismatch: Using ‘dtmfmode=info’ when the provider sends RFC2833 results in the IVR playing audio but ignoring all user keypresses.
• Priority Call Handling: Set the QUEUE_PRIORITY variable to 15 for VIP menu selections, ensuring these callers bypass standard customers in the sales queue.
• Pitfall: Permission Denied: Failing to chown the recording directory to the ‘asterisk’ user prevents MixMonitor from saving files, often leading to silent call drops.

References:

• https://dev.to/moisi_trungu_31647b7ac300/vicidial-ivr-setup-with-asterisk-inbound-call-menus-2f4k