vicidial-config-validator

Validate VICIdial campaign settings and calculate call center KPIs. Catches misconfigurations before they burn through leads or violate FTC rules.

Built by ViciStack -- we tune VICIdial systems for a living.

Install

npm install vicidial-config-validator

Quick Start

const { validateCampaign, campaignHealth } = require('vicidial-config-validator');

// Validate a campaign config before deploying it
const result = validateCampaign({
  dial_method: 'ADAPT_TAPERED',
  dial_timeout: 26,
  max_trunk_lines: 120,
  agent_count: 20,
  drop_rate_limit: 2,
  hopper_level: 200,
  dial_statuses: ['NEW', 'NA', 'B'],
  caller_id: '3145551234'
});

console.log(result);
// { valid: true, errors: [], warnings: [] }

Campaign Validator

The main use case. Pass your campaign config object and get back errors (hard failures) and warnings (things that will hurt performance or compliance).

const { validateCampaign } = require('vicidial-config-validator');

const result = validateCampaign({
  dial_method: 'RATIO',
  dial_timeout: 12,
  drop_rate_limit: 5,
  dial_statuses: ['NEW', 'DNC'],
  caller_id: '0000000000'
});

console.log(result.valid);   // false
console.log(result.errors);
// [
//   'dial_timeout must be between 10 and 120 seconds (got 12)' -- wait, 12 is valid but warns
//   'drop_rate_limit of 5% exceeds FTC 3% Safe Harbor threshold. This can result in fines.',
//   'dial_statuses includes DNC/DNCL. Calling Do-Not-Call numbers violates TCPA/TSR regulations.',
//   'caller_id looks like a placeholder. Invalid CIDs cause low answer rates and ...'
// ]

What it checks

| Field | Errors | Warnings | |---|---|---| | dial_method | Invalid method name | -- | | dial_timeout | Outside 10-120s | Under 20s (misses VM), over 60s (wastes trunks) | | max_trunk_lines / agent_count | -- | Ratio > 5:1 (drops), < 1:1 (idle agents) | | adaptive_intensity | Outside 0-1 | Above 0.5 (spike risk) | | drop_rate_limit | Over 3% (FTC violation) | Over 2% (close to limit) | | hopper_level | Below 1 | Too low for agent count, above 5000 | | dial_statuses | Contains DNC/DNCL | Contains SALE, unknown statuses | | local_call_time | -- | Before 8 AM or after 9 PM (TCPA) | | caller_id | Placeholder numbers | Short numbers | | amd_enabled | -- | AMD + RATIO dialing conflict |

Trunk Validator

const { validateTrunk } = require('vicidial-config-validator');

validateTrunk({
  host: 'sip.carrier.com',
  port: 5060,
  codecs: ['ulaw', 'g729'],
  max_channels: 60
});
// { valid: true, errors: [], warnings: [] }

Agent Validator

const { validateAgent } = require('vicidial-config-validator');

validateAgent({
  user_id: '1001',
  phone_login: '1001',
  phone_pass: 'test1234',
  user_level: 9
});
// { valid: true, errors: [], warnings: ['user_level 9 grants admin access...'] }

KPI Calculators

Every KPI function returns the calculated metric plus a rating and benchmark so you know whether the number is healthy without looking it up.

const {
  answerRate, abandonRate, agentUtilization,
  averageHandleTime, conversionRate, callsPerAgentHour,
  listPenetration, estimateTrunks, campaignHealth
} = require('vicidial-config-validator');

// Individual metrics
answerRate(200, 1000);
// { rate: 20, rating: 'good', benchmark: '15-25% is typical for outbound' }

abandonRate(5, 200);
// { rate: 2.5, compliant: true, rating: 'compliant', ftc_limit: 3 }

agentUtilization(1800, 3600);
// { rate: 50, rating: 'optimal', benchmark: '40-60% is healthy for predictive dialing' }

estimateTrunks(20, 2.5);
// { trunksNeeded: 60, formula: 'ceil(20 agents * 2.5 ratio * 1.2 buffer) = 60' }

Full Campaign Health Report

Pass all your stats at once and get a complete health report:

const report = campaignHealth({
  dialed: 5000,
  answered: 1000,
  abandoned: 20,
  conversions: 80,
  talkSeconds: 180000,
  wrapSeconds: 30000,
  loggedSeconds: 288000,
  agentCount: 10,
  hours: 8,
  leadsDialed: 4500,
  totalLeads: 5000
});

// Returns all KPIs with ratings and benchmarks
console.log(report.abandonRate.compliant); // true
console.log(report.conversionRate.rate);   // 8

Use Cases

• Pre-flight checks -- validate campaign settings before launching. We wrote this after seeing too many shops burn through 50K leads with a bad dial timeout or DNC leads mixed into the hopper. More war stories at vicistack.com/blog.

• Compliance monitoring -- check abandon rates against FTC 3% Safe Harbor in real time. If you're running predictive and not tracking this, you're asking for trouble. See our writeup on FTC compliance for predictive dialers.

• Shift reporting -- generate KPI snapshots for managers. The campaignHealth() function takes raw stats from vicidial_campaign_stats and returns everything a floor supervisor needs.

• Capacity planning -- use estimateTrunks() to right-size your SIP trunk order before scaling up agents. Over-provisioning wastes money; under-provisioning causes agent idle time.

TypeScript

Full type definitions included. Import types for CampaignConfig, TrunkConfig, AgentConfig, CampaignStats, etc.

import { validateCampaign, CampaignConfig, ValidationResult } from 'vicidial-config-validator';

const config: CampaignConfig = {
  dial_method: 'ADAPT_TAPERED',
  dial_timeout: 30,
  drop_rate_limit: 2
};

const result: ValidationResult = validateCampaign(config);

About

Built and maintained by ViciStack. We optimize VICIdial and Asterisk call center systems -- if your agents are sitting idle or your drop rate is creeping up, reach out.

License

MIT