Quickstart

Installation

npm install @thornebridge/vicijs

Agent API — Control Agent Sessions

import { ViciAgent } from 'vicijs';

const agent = new ViciAgent({
  baseUrl: 'https://dialer.example.com',
  user: 'apiuser',
  pass: 'apipass',
  agentUser: '1001',
});

// Dial a number
await agent.dial({ value: '5551234567', search: 'YES' });

// Pause / resume
await agent.pause('PAUSE');
await agent.pause('RESUME');

// Transfer to another group
await agent.transferConference({
  value: 'LOCAL_CLOSER',
  ingroupChoices: 'SALESLINE',
});

// Hangup and disposition
await agent.hangup();
await agent.setStatus({ value: 'SALE' });

Admin API — Manage Everything Else

import { ViciAdmin } from 'vicijs';

const admin = new ViciAdmin({
  baseUrl: 'https://dialer.example.com',
  user: 'apiuser',
  pass: 'apipass',
});

// Add a lead
await admin.leads.add({
  phoneNumber: '5551234567',
  listId: 101,
  firstName: 'John',
  lastName: 'Doe',
});

// Monitor an agent in real-time
const status = await admin.monitoring.agentStatus({
  agentUser: '1001',
});

Configuration

Agent API Reference

The ViciAgent class wraps all 31 functions of the ViciDial Agent API at /agc/api.php. Every method requires the agent to be logged into a ViciDial session.

Call Control

Agent State

Lead Management

Recording

Notifications & Misc

Admin API Reference

The ViciAdmin class wraps all 61 functions of the ViciDial Non-Agent API at /vicidial/non_agent_api.php, organized into 10 domain sub-clients.

admin.leads — Lead Management (11 functions)

admin.users — User Management (6 functions)

admin.monitoring — Real-Time (6 functions)

admin.reporting — Data Export (6 functions)

Other Domains

Error Handling

ViciJS throws typed errors for every failure mode. All errors extend ViciError and include the raw ViciDial response.

Error Hierarchy

Usage

import {
  ViciValidationError,
  ViciAuthError,
  ViciTimeoutError,
} from 'vicijs';

try {
  await admin.leads.add({ phoneNumber: '5551234567', listId: 101 });
} catch (err) {
  if (err instanceof ViciTimeoutError) {
    console.log(`Timed out after ${err.timeoutMs}ms`);
  } else if (err instanceof ViciValidationError) {
    console.log('Validation:', err.details);
    console.log('Raw:', err.raw);
  } else if (err instanceof ViciAuthError) {
    console.log('Check credentials');
  }
}

Error Classification

ViciDial errors are automatically classified by message pattern:

Webhooks & Callbacks

ViciDial can send HTTP requests to your server when events occur — calls answered, dispositions set, agents paused, leads created. ViciJS provides typed parsers, URL builders, and an event router for all 7 webhook types.

Webhook Types (7)

Building Callback URLs

Use buildCallbackUrl() to construct URLs with ViciDial's --A--variable--B-- template syntax. Paste the output into your ViciDial campaign settings.

import { buildCallbackUrl, CallbackVariable } from '@thornebridge/vicijs';

const url = buildCallbackUrl({
  baseUrl: 'https://hooks.example.com/vici/dispo',
  variables: [
    CallbackVariable.LEAD_ID,
    CallbackVariable.DISPO,
    CallbackVariable.PHONE_NUMBER,
    CallbackVariable.TALK_TIME,
    CallbackVariable.RECORDING_FILENAME,
  ],
  staticParams: { type: 'dispo_callback' },
});
// → "https://hooks.example.com/vici/dispo?type=dispo_callback&lead_id=--A--lead_id--B--&..."

For Agent Events Push, use the convenience function:

import { buildEventPushUrl } from '@thornebridge/vicijs';

const eventUrl = buildEventPushUrl(
  'https://hooks.example.com/vici/events',
  { type: 'agent_event' },
);
// Includes: user, event, message, lead_id, counter, epoch, agent_log_id

For cross-origin requests from the agent screen, wrap with wrapWithGet2Post():

import { wrapWithGet2Post } from '@thornebridge/vicijs';

const proxied = wrapWithGet2Post({
  externalUrl: eventUrl,
  type: 'event',
});
// → "get2post.php?uniqueid=--A--epoch--B--.--A--agent_log_id--B--&type=event&HTTPURLTOPOST=..."

Webhook Router

The ViciWebhookRouter parses incoming requests and dispatches to typed handlers.

import { ViciWebhookRouter, AgentEvent } from '@thornebridge/vicijs';

const router = new ViciWebhookRouter();

// Handle by webhook type
router.on('dispo_callback', (payload) => {
  console.log(`Lead ${payload.lead_id} dispo: ${payload.dispo}`);
  console.log(`Talk time: ${payload.talk_time}s`);
});

router.on('start_call', (payload) => {
  console.log(`Call started: ${payload.phone_number}`);
});

router.on('dead_call', (payload) => {
  console.log(`Customer hung up: ${payload.lead_id}`);
});

// Handle specific agent events
router.onEvent(AgentEvent.CALL_ANSWERED, (payload) => {
  console.log(`Agent ${payload.user} answered a call`);
});

router.onEvent(AgentEvent.DISPO_SET, (payload) => {
  console.log(`Agent ${payload.user} set disposition`);
});

// Express integration
app.get('/vici/webhook', (req, res) => {
  router.handle(req.url);  // auto-detects type from ?type= param
  res.send('OK');
});

// Or use separate routes with explicit types
app.get('/vici/dispo', (req, res) => {
  router.handleAs('dispo_callback', req.url);
  res.send('OK');
});

Direct Parsing

Parse webhooks without a router using the individual parsers:

import {
  parseDispoCallback,
  parseAgentEvent,
  parseStartCallback,
  parseNoAgentCallback,
  parseAddLeadCallback,
  parseDeadCallCallback,
  parsePauseMaxCallback,
} from '@thornebridge/vicijs';

// Parse from URL, query string, or URLSearchParams
const payload = parseDispoCallback(req.url);
console.log(payload.dispo);            // 'SALE'
console.log(payload.phone_number);     // '5551234567'
console.log(payload.recording_filename); // '20250115-103000_1001'

Callback Variables (103)

All 103 ViciDial callback URL template variables are available via the CallbackVariable enum, organized by category:

Full API Reference

Every interface, every parameter, every type. 80 response schemas, 103 callback variables. Generated from source.

Response Parsing

ViciDial returns pipe-delimited text. Use built-in schemas to map fields:

import { mapFields, ADMIN_SCHEMAS } from 'vicijs';

const result = await admin.leads.allInfo({ leadId: 12345 });
const lead = mapFields(result.rawData, ADMIN_SCHEMAS.lead_all_info);

lead.first_name;     // 'John'
lead.phone_number;   // '5551234567'
lead.status;          // 'SALE'

Agent API — ViciAgent

Endpoint: /agc/api.php — All methods require agentUser in config.

VersionResponse VersionResponse

WebserverResponse WebserverResponse

DialParams external_dial

ExternalStatusParams external_status

ChangeIngroupsParams change_ingroups

UpdateFieldsParams update_fields

SetTimerActionParams set_timer_action

RaCallControlParams ra_call_control

TransferConferenceParams transfer_conference

RecordingParams recording

StereoRecordingParams stereo_recording

AudioPlaybackParams audio_playback

SwitchLeadParams switch_lead

ForceFronterParams force_fronter_leave_3way

SendNotificationParams send_notification

VmMessageParams vm_message

RefreshPanelParams refresh_panel

ExternalAddLeadParams external_add_lead

WebphoneUrlResponse WebphoneUrlResponse

StLoginLogParams st_login_log

Admin API — ViciAdmin

Endpoint: /vicidial/non_agent_api.php

Leads (admin.leads)

AddLeadParams add_lead

UpdateLeadParams update_lead

BatchUpdateLeadParams batch_update_lead

LeadFieldInfoParams lead_field_info

LeadAllInfoParams lead_all_info extends OutputParams

LeadCallbackInfoParams lead_callback_info extends OutputParams

LeadSearchParams lead_search

LeadStatusSearchParams lead_status_search

CccLeadInfoParams ccc_lead_info extends OutputParams

CallidInfoParams callid_info extends OutputParams

Users (admin.users)

AddUserParams add_user

UpdateUserParams update_user

CopyUserParams copy_user

UpdateRemoteAgentParams update_remote_agent

UserDetailsParams user_details extends OutputParams

AgentCampaignsParams agent_campaigns extends OutputParams

Monitoring (admin.monitoring)

BlindMonitorParams blind_monitor

AgentIngroupInfoParams agent_ingroup_info

AgentStatusParams agent_status extends OutputParams

UserGroupStatusParams user_group_status extends OutputParams

InGroupStatusParams in_group_status extends OutputParams

LoggedInAgentsParams logged_in_agents extends OutputParams

Reporting (admin.reporting)

RecordingLookupParams recording_lookup extends OutputParams

DidLogExportParams did_log_export extends OutputParams

AgentStatsExportParams agent_stats_export extends OutputParams

CallStatusStatsParams call_status_stats extends OutputParams

CallDispoReportParams call_dispo_report extends OutputParams

PhoneNumberLogParams phone_number_log extends OutputParams

Campaigns (admin.campaigns)

UpdateCampaignParams update_campaign

CampaignsListParams campaigns_list extends OutputParams

HopperListParams hopper_list extends OutputParams

HopperBulkInsertParams hopper_bulk_insert

Lists (admin.lists)

AddListParams add_list

UpdateListParams update_list

ListInfoParams list_info extends OutputParams

ListCustomFieldsParams list_custom_fields extends OutputParams

Phones (admin.phones)

AddPhoneParams add_phone

UpdatePhoneParams update_phone

AddPhoneAliasParams add_phone_alias

UpdatePhoneAliasParams update_phone_alias

DIDs (admin.dids)

AddDidParams add_did

CopyDidParams copy_did

UpdateDidParams update_did

DNC (admin.dnc)

DncPhoneParams add_dnc_phone

FpgPhoneParams add_fpg_phone

System (admin.system)

CheckPhoneNumberParams check_phone_number

AddGroupAliasParams add_group_alias

UpdateCidGroupEntryParams update_cid_group_entry

UpdateAltUrlParams update_alt_url

UpdatePresetsParams update_presets

UpdateLogEntryParams update_log_entry

Status Code Enums (86 codes)

Agent Events (49 events)

Browser / CORS

Configure CORS on your ViciDial server via agc/options.php and vicidial/options.php. See official CORS docs. Never set to '*'.

Links