### Install ViciJS

Source: https://github.com/thornebridge/vicijs/blob/main/README.md

Install the package via npm.

```bash
npm install @thornebridge/vicijs
```

--------------------------------

### List Audio Files

Source: https://context7.com/thornebridge/vicijs/llms.txt

Get a list of available audio files on the Vici server. The 'format' and 'stage' parameters can be used to customize the output.

```typescript
// List audio files
const sounds = await admin.system.soundsList({
  format: 'csv',
  stage: 'date',
});
```

--------------------------------

### Get callback information for a lead with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve callback details for a specific lead, with options for search location.

```typescript
// Get callback info
const callbackInfo = await admin.leads.callbackInfo({
  leadId: 12345,
  searchLocation: 'ARCHIVE_FIRST',
});
```

--------------------------------

### Integrate Webhooks with Express

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Examples of integrating ViciJS routers into an Express application using auto-detection or explicit route handling.

```javascript
// 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');
});
```

--------------------------------

### Get all lead info with custom fields using ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve comprehensive lead information, including custom fields, by lead ID.

```typescript
// Get all lead info with custom fields
const leadInfo = await admin.leads.allInfo({
  leadId: 12345,
  customFields: 'Y',
});
```

--------------------------------

### Get user details with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve detailed information for a specific user account.

```typescript
// Get user details
const details = await admin.users.details({ agentUser: 'agent1001' });
```

--------------------------------

### Get API Version

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve the current version and build information of the Vici API. This is useful for compatibility checks and debugging.

```typescript
// Get API version
const version = await admin.system.version();
console.log(version.data); // { version: '2.4-34', build: '250720-1841', ... }
```

--------------------------------

### Initialize and Use ViciAdmin

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Configure the ViciAdmin client to perform administrative tasks such as lead management and real-time monitoring.

```typescript
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',
});
```

--------------------------------

### Initialize ViciAdmin Client

Source: https://context7.com/thornebridge/vicijs/llms.txt

The ViciAdmin client provides access to 10 domain-specific sub-clients for system-wide management.

```typescript
import { ViciAdmin } from '@thornebridge/vicijs';

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

// Access domain sub-clients
admin.leads       // Lead management (11 methods)
admin.users       // User management (6 methods)
admin.campaigns   // Campaign management (4 methods)
admin.lists       // List management (4 methods)
admin.phones      // Phone management (4 methods)
admin.dids        // DID management (3 methods)
admin.dnc         // DNC management (4 methods)
admin.monitoring  // Real-time monitoring (6 methods)
admin.reporting   // Reporting/exports (6 methods)
admin.system      // System utilities (12 methods)
```

--------------------------------

### List Voicemail Boxes

Source: https://context7.com/thornebridge/vicijs/llms.txt

Get a list of all configured voicemail boxes. Useful for administrative tasks related to voicemail management.

```typescript
// List voicemail boxes
const voicemail = await admin.system.vmList();
```

--------------------------------

### Configure ViciJS Clients

Source: https://context7.com/thornebridge/vicijs/llms.txt

Initialize ViciAdmin and ViciAgent clients with custom timeouts, source identifiers, and fetch implementations.

```typescript
import { ViciAdmin, ViciAgent, ViciConfig, AgentConfig } from '@thornebridge/vicijs';

// Base configuration (for Admin client)
const adminConfig: ViciConfig = {
  baseUrl: 'https://dialer.example.com',  // ViciDial server URL
  user: 'apiuser',                         // API username
  pass: 'apipass',                         // API password
  source: 'mycrm',                         // Source identifier (max 20 chars, default: 'vicijs')
  timeout: 60000,                          // Request timeout in ms (default: 30000)
  fetch: customFetch,                      // Custom fetch for testing/proxying (optional)
};

const admin = new ViciAdmin(adminConfig);

// Agent configuration (extends base with agentUser)
const agentConfig: AgentConfig = {
  baseUrl: 'https://dialer.example.com',
  user: 'apiuser',
  pass: 'apipass',
  agentUser: '1001',  // Agent session to control
  timeout: 30000,
};

const agent = new ViciAgent(agentConfig);

// Using custom fetch for testing
const mockFetch = async (url: string, init?: RequestInit) => {
  console.log('Request:', url);
  return new Response('SUCCESS: test_function OK - data|here', {
    status: 200,
    headers: { 'Content-Type': 'text/plain' },
  });
};

const testAdmin = new ViciAdmin({
  baseUrl: 'https://test.example.com',
  user: 'test',
  pass: 'test',
  fetch: mockFetch,
});
```

--------------------------------

### Manage Admin Operations

Source: https://github.com/thornebridge/vicijs/blob/main/README.md

Initialize the ViciAdmin client to manage leads, users, campaigns, and reporting.

```typescript
import { ViciAdmin } from '@thornebridge/vicijs';

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

// Leads
await admin.leads.add({ phoneNumber: '5551234567', listId: 101, firstName: 'John' });
await admin.leads.update({ leadId: 12345, status: 'SALE' });
await admin.leads.batchUpdate({ leadIds: '1001,1002,1003', status: 'DNC' });
const lead = await admin.leads.allInfo({ leadId: 12345, customFields: 'Y' });

// Users
await admin.users.add({
  agentUser: 'newagent', agentPass: 'pass123',
  agentUserLevel: 7, agentFullName: 'New Agent', agentUserGroup: 'AGENTS',
});

// Campaigns
await admin.campaigns.update({ campaignId: 'SALES1', autoDialLevel: '3.0' });

// Real-time monitoring
const status = await admin.monitoring.agentStatus({ agentUser: '1001' });

// Reporting
const stats = await admin.reporting.agentStatsExport({
  datetimeStart: '2025-01-01+00:00:00',
  datetimeEnd: '2025-01-31+23:59:59',
});

// DNC
await admin.dnc.addPhone({ phoneNumber: '5551234567', campaignId: 'SYSTEM_INTERNAL' });
```

--------------------------------

### Get allowed campaigns and ingroups for an agent with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve a list of campaigns and ingroups that a specific agent is allowed to access.

```typescript
// Get allowed campaigns and ingroups for agent
const campaigns = await admin.users.agentCampaigns({ agentUser: 'agent1001' });
```

--------------------------------

### Handle Vici Webhook Events

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Sets up a ViciWebhookRouter to handle incoming webhook events like 'dispo_callback' and 'start_call'. Requires imports for ViciWebhookRouter and AgentEvent.

```javascript
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) => {
  // Handler for dead_call events
});
```

--------------------------------

### External API - Get Webphone URL

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Retrieves a webphone URL. This is likely used to initiate calls or access webphone functionalities.

```APIDOC
## GET /external/webphone_url

### Description
Retrieves a webphone URL. This endpoint is likely used to initiate calls or access webphone functionalities.

### Method
GET

### Endpoint
/external/webphone_url

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL to retrieve.

### Request Example
```json
{
  "url": "/vicidial/non_agent_api.php?function=get_webphone_url"
}
```

### Response
#### Success Response (200)
- **url** (string) - The webphone URL.

#### Response Example
```json
{
  "url": "http://your.vicidial.server/vicidial/webphone.php?user=testuser&pass=testpass"
}
```
```

--------------------------------

### Initialize ViciAdmin Client

Source: https://context7.com/thornebridge/vicijs/llms.txt

Instantiate the ViciAdmin client with your dialer's base URL and API credentials. This client is used for all subsequent API interactions.

```typescript
import { ViciAdmin } from '@thornebridge/vicijs';

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

--------------------------------

### Launch Blind Monitor on Agent's Call

Source: https://context7.com/thornebridge/vicijs/llms.txt

Initiate a real-time monitoring session (monitor, barge, or hijack) on an agent's active call. Requires agent's session ID and server IP. Ensure you have the necessary permissions.

```typescript
// Launch blind monitor on agent's call
await admin.monitoring.blindMonitor({
  phoneLogin: 'supervisor100',
  sessionId: '8600051',
  serverIp: '192.168.1.100',
  stage: 'MONITOR',  // MONITOR, BARGE, HIJACK
});
```

--------------------------------

### Get custom field definitions for a list

Source: https://context7.com/thornebridge/vicijs/llms.txt

Fetch the definitions of custom fields associated with a list. You can specify the order for custom fields.

```typescript
// Get custom field definitions
const customFields = await admin.lists.customFields({
  listId: 101,
  customOrder: 'alpha_up',
});
```

--------------------------------

### Manage Agent Screen and Lead Actions

Source: https://context7.com/thornebridge/vicijs/llms.txt

Use these methods to update lead information, manage manual dial queues, and control agent screen states.

```typescript
import { ViciAgent } from '@thornebridge/vicijs';

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

// Update customer fields on agent screen
await agent.updateFields({
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  comments: 'Interested in premium package',
  city: 'New York',
  state: 'NY',
  postalCode: '10001',
});

// Add a new lead to agent's manual dial queue
await agent.addLead({
  phoneNumber: '5551234567',
  phoneCode: '1',
  firstName: 'Jane',
  lastName: 'Smith',
  dncCheck: 'YES',
  campaignDncCheck: 'YES',
});

// Change agent's inbound group assignments
await agent.changeIngroups({
  value: 'CHANGE',    // CHANGE, REMOVE, ADD
  blended: 'YES',     // YES, NO (blended calls enabled)
  ingroupChoices: 'SALESLINE|SUPPORT|BILLING',
  setAsDefault: 'YES',
});

// Switch lead on live inbound call
await agent.switchLead({ leadId: 67890 });
// Or by vendor code
await agent.switchLead({ vendorLeadCode: 'VLC12345' });

// Refresh agent screen panels
await agent.refreshPanel({
  formreload: 1,
  scriptreload: 1,
  callbacksreload: 1,
});

// Set a timed action on agent screen
await agent.setTimerAction({
  value: 'D1_DIAL',    // Timer action type
  notes: 'Follow up reminder',
  rank: 60,            // Seconds before action triggers
});
```

--------------------------------

### Get list information with counts

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve details for a specific list, including dialable and total lead counts. Set 'dialableCount' and 'leadsCounts' to 'Y'.

```typescript
// Get list info with dialable count
const listInfo = await admin.lists.info({
  listId: 101,
  dialableCount: 'Y',
  leadsCounts: 'Y',
});
```

--------------------------------

### Copy an existing user with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Create a new user account by copying settings from an existing user.

```typescript
// Copy an existing user
await admin.users.copy({
  agentUser: 'agent1002',
  agentPass: 'newpass123',
  agentFullName: 'Copied Agent',
  sourceUser: 'agent1001',
});
```

--------------------------------

### Initialize and Use ViciAgent

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Configure the ViciAgent client to perform session-based actions like dialing, pausing, and transferring calls.

```typescript
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' });
```

--------------------------------

### Get single field value for a lead with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve the value of a specific lead field, including custom fields, by lead ID.

```typescript
// Get single field value
const fieldValue = await admin.leads.fieldInfo({
  leadId: 12345,
  fieldName: 'email',
  customFields: 'Y',
});
```

--------------------------------

### Dearchive a lead with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Move a lead from the archive back to the active status.

```typescript
// Dearchive a lead (move from archive to active)
await admin.leads.dearchive(12345);
```

--------------------------------

### Get Call Status Statistics

Source: https://context7.com/thornebridge/vicijs/llms.txt

Obtain statistics on call statuses for specified campaigns and a query date. This helps in analyzing call outcomes and agent performance.

```typescript
// Get call status statistics
const statusStats = await admin.reporting.callStatusStats({
  campaigns: 'SALES1-SUPPORT',
  queryDate: '2025-01-15',
  statuses: 'SALE-NI-DNC',
});
```

--------------------------------

### Get Inbound Group Status

Source: https://context7.com/thornebridge/vicijs/llms.txt

Obtain the current status of inbound call groups. This is useful for monitoring call queues and agent availability for incoming calls.

```typescript
// Get inbound group status
const groupStatus = await admin.monitoring.inGroupStatus({
  inGroups: 'SALESLINE|SUPPORT|BILLING',
});
```

--------------------------------

### Build Agent Event Push URL

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Creates a URL for agent event push notifications using buildEventPushUrl. Requires the vicijs library.

```javascript
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
```

--------------------------------

### Get User Group Status

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve the status information for specified user groups. This helps in understanding the aggregate status of agents within different roles.

```typescript
// Get user group status
const groupStatus = await admin.monitoring.userGroupStatus({
  userGroups: 'AGENTS|SUPERVISORS',
});
```

--------------------------------

### Build ViciDial Callback URL

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Constructs a callback URL for ViciDial dispositions using buildCallbackUrl. Requires imports for buildCallbackUrl and CallbackVariable.

```javascript
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--&..."
```

--------------------------------

### Add a new user with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Create a new user account with detailed settings including group assignments and phone configurations.

```typescript
import { ViciAdmin } from '@thornebridge/vicijs';

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

// Add a new user
await admin.users.add({
  agentUser: 'newagent',
  agentPass: 'securepass123',
  agentUserLevel: 7,
  agentFullName: 'New Agent',
  agentUserGroup: 'AGENTS',
  phoneLogin: '100',
  phonePass: 'phonepass',
  hotkeysActive: 1,
  voicemailId: 'newagent',
  email: 'newagent@company.com',
  agentChooseIngroups: 1,
  agentChooseBlended: 1,
  inGroups: 'SALESLINE|SUPPORT|BILLING',
});
```

--------------------------------

### Get Single Agent Status

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve the real-time status of a specific agent, optionally including their IP address. Use this to check agent availability and activity.

```typescript
// Get single agent status
const agentStatus = await admin.monitoring.agentStatus({
  agentUser: '1001',
  includeIp: 'YES',
});
```

--------------------------------

### Get Phone Number Call History

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve the call history for one or more phone numbers. The 'detail' and 'type' parameters allow for granular control over the information returned.

```typescript
// Get phone number call history
const phoneLog = await admin.reporting.phoneNumberLog({
  phoneNumber: '5551234567,5559876543',
  detail: 'EXTENDED',
  type: 'ALL',
});
```

--------------------------------

### Admin API - Lead Management

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

APIs for managing leads within the ViciDial system, including adding, updating, and searching.

```APIDOC
## POST admin.leads.add(params)

### Description
Adds a new lead with over 45 parameters, including DNC checks, hopper, and callback scheduling.

### Method
POST

### Endpoint
/admin/leads/add

### Parameters
#### Request Body
- **params** (object) - Required - Object containing lead data and associated parameters.
```

```APIDOC
## POST admin.leads.update(params)

### Description
Updates an existing lead with over 50 parameters, supporting search, callbacks, and hopper management.

### Method
POST

### Endpoint
/admin/leads/update

### Parameters
#### Request Body
- **params** (object) - Required - Object containing lead identifier and updated data.
```

```APIDOC
## POST admin.leads.batchUpdate(params)

### Description
Updates multiple leads simultaneously, with a maximum limit of 100 leads per request.

### Method
POST

### Endpoint
/admin/leads/batchUpdate

### Parameters
#### Request Body
- **params** (object) - Required - Object containing batch update data for leads.
```

```APIDOC
## GET admin.leads.fieldInfo(params)

### Description
Retrieves the value of a single field for a specific lead.

### Method
GET

### Endpoint
/admin/leads/fieldInfo

### Parameters
#### Query Parameters
- **leadId** (integer) - Required - The ID of the lead.
- **fieldName** (string) - Required - The name of the field to retrieve.
```

```APIDOC
## GET admin.leads.allInfo(params)

### Description
Retrieves all data for a lead, including optional custom fields.

### Method
GET

### Endpoint
/admin/leads/allInfo

### Parameters
#### Query Parameters
- **leadId** (integer) - Required - The ID of the lead.
- **customFields** (boolean) - Optional - Whether to include custom fields.
```

```APIDOC
## GET admin.leads.callbackInfo(params)

### Description
Retrieves information about scheduled callbacks for leads.

### Method
GET

### Endpoint
/admin/leads/callbackInfo

### Parameters
#### Query Parameters
- **leadId** (integer) - Optional - Filter by lead ID.
- **campaignId** (string) - Optional - Filter by campaign ID.
```

```APIDOC
## GET admin.leads.search(params)

### Description
Searches for leads based on their phone number.

### Method
GET

### Endpoint
/admin/leads/search

### Parameters
#### Query Parameters
- **phoneNumber** (string) - Required - The phone number to search for.
```

```APIDOC
## GET admin.leads.statusSearch(params)

### Description
Searches for leads based on their status and a date range.

### Method
GET

### Endpoint
/admin/leads/statusSearch

### Parameters
#### Query Parameters
- **status** (string) - Required - The lead status to search for.
- **startDate** (string) - Required - The start date for the search (YYYY-MM-DD).
- **endDate** (string) - Required - The end date for the search (YYYY-MM-DD).
```

```APIDOC
## GET admin.leads.cccInfo(params)

### Description
Retrieves cross-cluster call lead data.

### Method
GET

### Endpoint
/admin/leads/cccInfo

### Parameters
#### Query Parameters
- **leadId** (integer) - Required - The ID of the lead.
```

```APIDOC
## GET admin.leads.callidInfo(params)

### Description
Retrieves call information using a call ID.

### Method
GET

### Endpoint
/admin/leads/callidInfo

### Parameters
#### Query Parameters
- **callId** (string) - Required - The ID of the call.
```

```APIDOC
## POST admin.leads.dearchive(leadId)

### Description
Moves a lead from the archive back to the active status.

### Method
POST

### Endpoint
/admin/leads/dearchive

### Parameters
#### Request Body
- **leadId** (integer) - Required - The ID of the lead to dearchive.
```

--------------------------------

### Get Agent Ingroup Information

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve detailed information about an agent's ingroup assignments and status. Use this for specific agent performance analysis within their assigned groups.

```typescript
// Get agent ingroup info
const ingroupInfo = await admin.monitoring.agentIngroupInfo({
  agentUser: '1001',
  stage: 'info',
});
```

--------------------------------

### Get All Logged-In Agents

Source: https://context7.com/thornebridge/vicijs/llms.txt

Fetch a list of all agents currently logged in, with options to filter by campaign and user group, and control the output format. Useful for an overview of active agents.

```typescript
// Get all logged-in agents
const loggedIn = await admin.monitoring.loggedInAgents({
  campaigns: 'SALES1|SUPPORT',
  userGroups: 'AGENTS|SUPERVISORS',
  showSubStatus: 'YES',
  stage: 'csv',
  header: 'YES',
});
```

--------------------------------

### Add a phone extension

Source: https://context7.com/thornebridge/vicijs/llms.txt

Register a new phone extension with its configuration details, including server IP, protocol, and security credentials.

```typescript
// Add a phone extension
await admin.phones.add({
  extension: '100',
  dialplanNumber: '100',
  voicemailId: '100',
  phoneLogin: '100',
  phonePass: 'phonepass123',
  serverIp: '192.168.1.100',
  protocol: 'SIP',
  registrationPassword: 'sippass123',
  phoneFullName: 'Agent Phone 100',
  outboundCid: '8005551234',
  isWebphone: 'Y',
  webphoneAutoAnswer: 'Y',
});
```

--------------------------------

### Get Call Disposition Report

Source: https://context7.com/thornebridge/vicijs/llms.txt

Generate a report detailing call dispositions for a given period and campaigns, with options to include status breakdowns and percentages. Ideal for analyzing campaign effectiveness.

```typescript
// Get call disposition report
const dispoReport = await admin.reporting.callDispoReport({
  campaigns: 'SALES1-SUPPORT',
  queryDate: '2025-01-01',
  endDate: '2025-01-31',
  statusBreakdown: '1',
  showPercentages: '1',
  stage: 'csv',
  header: 'YES',
});
```

--------------------------------

### POST /vicidial/non_agent_api.php - Add Lead

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Adds a new lead to the system. This endpoint supports a comprehensive set of parameters for lead information.

```APIDOC
## POST /vicidial/non_agent_api.php - Add Lead

### Description
Adds a new lead to the system with detailed information.

### Method
POST

### Endpoint
/vicidial/non_agent_api.php

### Parameters
#### Request Body
- **phoneNumber** (string) - Required - The primary phone number for the lead.
- **phoneCode** (string) - Optional - The country code for the phone number.
- **listId** (number) - Optional - The ID of the list to which the lead should be added.
- **dncCheck** (DNCCheck) - Optional - Specifies DNC check status.
- **campaignDncCheck** (DNCCheck) - Optional - Specifies campaign DNC check status.
- **campaignId** (string) - Optional - The ID of the campaign.
- **addToHopper** ("Y", "N") - Optional - Whether to add the lead to the hopper.
- **hopperPriority** (number) - Optional - Priority for the hopper.
- **hopperLocalCallTimeCheck** ("Y", "N") - Optional - Whether to check local call time for the hopper.
- **duplicateCheck** (DuplicateCheck | string) - Optional - Specifies duplicate check behavior.
- **usacanPrefixCheck** ("Y", "N") - Optional - Whether to perform US/Canada prefix check.
- **usacanAreacodeCheck** ("Y", "N") - Optional - Whether to perform US/Canada area code check.
- **nanpaAcPrefixCheck** ("Y", "N") - Optional - Whether to perform NANPA AC prefix check.
- **customFields** ("Y", "N") - Optional - Whether to include custom fields.
- **tzMethod** (TZMethod) - Optional - Timezone method to use.
- **lookupState** ("Y", "N") - Optional - Whether to look up the state.
- **callback** ("Y", "N") - Optional - Whether to set a callback.
- **callbackStatus** (string) - Optional - Status for the callback.
- **callbackDatetime** (string) - Optional - Datetime for the callback.
- **callbackType** (CallbackType) - Optional - Type of callback.
- **callbackUser** (string) - Optional - User for the callback.
- **callbackComments** (string) - Optional - Comments for the callback.
- **listExistsCheck** ("Y", "N") - Optional - Whether to check if the list exists.
- **vendorLeadCode** (string) - Optional - Vendor-specific lead code.
- **sourceId** (string) - Optional - Source ID of the lead.
- **gmtOffsetNow** (string) - Optional - GMT offset now.
- **title** (string) - Optional - Title of the lead.
- **firstName** (string) - Optional - First name of the lead.
- **middleInitial** (string) - Optional - Middle initial of the lead.
- **lastName** (string) - Optional - Last name of the lead.
- **address1** (string) - Optional - Address line 1.
- **address2** (string) - Optional - Address line 2.
- **address3** (string) - Optional - Address line 3.
- **city** (string) - Optional - City.
- **state** (string) - Optional - State.
- **province** (string) - Optional - Province.
- **postalCode** (string) - Optional - Postal code.
- **countryCode** (string) - Optional - Country code.
- **gender** (Gender) - Optional - Gender of the lead.
- **dateOfBirth** (string) - Optional - Date of birth.
- **altPhone** (string) - Optional - Alternate phone number.
- **email** (string) - Optional - Email address.
- **securityPhrase** (string) - Optional - Security phrase.
- **comments** (string) - Optional - Comments about the lead.
- **multiAltPhones** (string) - Optional - Multiple alternate phone numbers.
- **rank** (number) - Optional - Rank of the lead.
- **owner** (string) - Optional - Owner of the lead.
- **entryListId** (number) - Optional - Entry list ID.

### Request Example
```json
{
  "phoneNumber": "1234567890",
  "listId": 101,
  "firstName": "John",
  "lastName": "Doe",
  "email": "john.doe@example.com"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.

#### Response Example
```json
{
  "message": "Lead added successfully."
}
```
```

--------------------------------

### Admin API - Leads

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Endpoints for managing leads within the ViciDial system.

```APIDOC
## POST /vicidial/admin.php

### Description
Adds a new lead to the system. This endpoint is part of the Admin API for lead management.

### Method
POST

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **ADD_LEAD** (string) - Required - Indicates the action to add a lead.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **agent_user** (string) - Required - The agent username associated with the lead.
- **campaign** (string) - Required - The campaign to which the lead belongs.
- **list_id** (string) - Required - The ID of the list the lead is associated with.

#### Request Body
- **phone_number** (string) - Required - The phone number of the lead.
- **first_name** (string) - Optional - The first name of the lead.
- **last_name** (string) - Optional - The last name of the lead.
- **lead_id** (string) - Optional - A unique identifier for the lead. If not provided, the system may generate one.

### Request Example
```json
{
  "phone_number": "5551234567",
  "first_name": "John",
  "last_name": "Doe"
}
```

### Response
#### Success Response (200)
- **lead_id** (string) - The ID of the newly created lead.
- **status** (string) - The status of the operation (e.g., 'SUCCESS').

#### Response Example
```json
{
  "lead_id": "987654",
  "status": "SUCCESS"
}
```
```

```APIDOC
## POST /vicidial/admin.php

### Description
Updates an existing lead's information. This endpoint is part of the Admin API for lead management.

### Method
POST

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **UPDATE_LEAD** (string) - Required - Indicates the action to update a lead.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **lead_id** (string) - Required - The ID of the lead to update.

#### Request Body
- **phone_number** (string) - Optional - The updated phone number.
- **first_name** (string) - Optional - The updated first name.
- **last_name** (string) - Optional - The updated last name.
- **status** (string) - Optional - The updated status of the lead.

### Request Example
```json
{
  "phone_number": "5559876543",
  "status": "UPDATED"
}
```

### Response
#### Success Response (200)
- **lead_id** (string) - The ID of the updated lead.
- **status** (string) - The status of the operation (e.g., 'SUCCESS').

#### Response Example
```json
{
  "lead_id": "987654",
  "status": "SUCCESS"
}
```
```

```APIDOC
## POST /vicidial/admin.php

### Description
Performs a batch update on multiple leads. This endpoint is part of the Admin API for lead management.

### Method
POST

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **BATCH_UPDATE_LEAD** (string) - Required - Indicates the action to perform a batch update on leads.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.

#### Request Body
- **leads** (array) - Required - An array of lead objects to update. Each object must contain at least a `lead_id` and the fields to update.
  - **lead_id** (string) - Required - The ID of the lead.
  - **first_name** (string) - Optional - The updated first name.
  - **last_name** (string) - Optional - The updated last name.
  - **status** (string) - Optional - The updated status.

### Request Example
```json
{
  "leads": [
    {
      "lead_id": "987654",
      "first_name": "Jane",
      "status": "CONTACTED"
    },
    {
      "lead_id": "987655",
      "last_name": "Smith"
    }
  ]
}
```

### Response
#### Success Response (200)
- **status** (string) - The status of the operation (e.g., 'SUCCESS').
- **updated_count** (integer) - The number of leads successfully updated.

#### Response Example
```json
{
  "status": "SUCCESS",
  "updated_count": 2
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Retrieves information about a specific lead field. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **LEAD_FIELD_INFO** (string) - Required - Indicates the action to retrieve lead field information.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **field_id** (string) - Required - The ID of the lead field to retrieve information for.

### Response
#### Success Response (200)
- **field_id** (string) - The ID of the lead field.
- **field_label** (string) - The label of the lead field.
- **field_type** (string) - The type of the lead field.
- **field_order** (string) - The order of the lead field.

#### Response Example
```json
{
  "field_id": "1",
  "field_label": "First Name",
  "field_type": "INPUT",
  "field_order": "1"
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Retrieves all information for a specific lead. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **LEAD_ALL_INFO** (string) - Required - Indicates the action to retrieve all information for a lead.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **lead_id** (string) - Required - The ID of the lead.

### Response
#### Success Response (200)
- **lead_id** (string) - The ID of the lead.
- **phone_number** (string) - The phone number of the lead.
- **first_name** (string) - The first name of the lead.
- **last_name** (string) - The last name of the lead.
- **status** (string) - The status of the lead.
- ... (other lead fields)

#### Response Example
```json
{
  "lead_id": "987654",
  "phone_number": "5551234567",
  "first_name": "John",
  "last_name": "Doe",
  "status": "SALE"
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Retrieves callback information for a lead. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **LEAD_CALLBACK_INFO** (string) - Required - Indicates the action to retrieve lead callback information.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **lead_id** (string) - Required - The ID of the lead.

### Response
#### Success Response (200)
- **lead_id** (string) - The ID of the lead.
- **callback_date** (string) - The date of the callback.
- **callback_time** (string) - The time of the callback.
- **callback_user** (string) - The user assigned to the callback.

#### Response Example
```json
{
  "lead_id": "987654",
  "callback_date": "2023-10-27",
  "callback_time": "14:30:00",
  "callback_user": "agent1"
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Searches for leads based on specified criteria. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **LEAD_SEARCH** (string) - Required - Indicates the action to search for leads.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **search_field** (string) - Required - The field to search within (e.g., 'phone_number', 'first_name').
- **search_value** (string) - Required - The value to search for.
- **campaign** (string) - Optional - The campaign to filter results by.

### Response
#### Success Response (200)
- **leads** (array) - An array of lead objects matching the search criteria.
  - **lead_id** (string) - The ID of the lead.
  - **phone_number** (string) - The phone number.
  - **first_name** (string) - The first name.
  - **last_name** (string) - The last name.
  - **status** (string) - The status.

#### Response Example
```json
{
  "leads": [
    {
      "lead_id": "987654",
      "phone_number": "5551234567",
      "first_name": "John",
      "last_name": "Doe",
      "status": "SALE"
    }
  ]
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Searches for leads based on their status within a campaign. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **LEAD_STATUS_SEARCH** (string) - Required - Indicates the action to search for leads by status.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **status** (string) - Required - The lead status to search for.
- **campaign** (string) - Required - The campaign to search within.

### Response
#### Success Response (200)
- **leads** (array) - An array of lead objects matching the status and campaign.
  - **lead_id** (string) - The ID of the lead.
  - **phone_number** (string) - The phone number.
  - **first_name** (string) - The first name.
  - **last_name** (string) - The last name.
  - **status** (string) - The status.

#### Response Example
```json
{
  "leads": [
    {
      "lead_id": "987654",
      "phone_number": "5551234567",
      "first_name": "John",
      "last_name": "Doe",
      "status": "SALE"
    }
  ]
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Retrieves Call Center Customer (CCC) lead information. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **CCC_LEAD_INFO** (string) - Required - Indicates the action to retrieve CCC lead information.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **lead_id** (string) - Required - The ID of the lead.

### Response
#### Success Response (200)
- **lead_id** (string) - The ID of the lead.
- **ccc_status** (string) - The CCC status of the lead.
- **ccc_date** (string) - The date associated with the CCC status.

#### Response Example
```json
{
  "lead_id": "987654",
  "ccc_status": "ACTIVE",
  "ccc_date": "2023-10-27"
}
```
```

```APIDOC
## GET /vicidial/admin.php

### Description
Retrieves call ID information for a lead. This endpoint is part of the Admin API for lead management.

### Method
GET

### Endpoint
/vicidial/admin.php

### Parameters
#### Query Parameters
- **CALLID_INFO** (string) - Required - Indicates the action to retrieve call ID information.
- **user** (string) - Required - The username of the administrator.
- **pass** (string) - Required - The password of the administrator.
- **lead_id** (string) - Required - The ID of the lead.

### Response
#### Success Response (200)
- **lead_id** (string) - The ID of the lead.
- **call_id** (string) - The call ID associated with the lead.

#### Response Example
```json
{
  "lead_id": "987654",
  "call_id": "1234567890"
}
```
```

--------------------------------

### List all campaigns with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Retrieve a list of all available campaigns in the system.

```typescript
// List all campaigns
const allCampaigns = await admin.campaigns.list();
```

--------------------------------

### ViciAdmin API

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

The ViciAdmin class provides administrative functions for managing leads, users, campaigns, and system monitoring via /vicidial/non_agent_api.php.

```APIDOC
## GET /vicidial/non_agent_api.php

### Description
Performs administrative tasks including lead management and system monitoring.

### Method
GET

### Endpoint
/vicidial/non_agent_api.php

### Request Example
const admin = new ViciAdmin({ baseUrl: 'https://dialer.example.com', user: 'apiuser', pass: 'apipass' });
await admin.leads.add({ phoneNumber: '5551234567', listId: 101, firstName: 'John', lastName: 'Doe' });
```

--------------------------------

### Wrap URL for Cross-Origin Requests

Source: https://github.com/thornebridge/vicijs/blob/main/docs/index.html

Uses wrapWithGet2Post to proxy cross-origin requests from the agent screen. Requires the vicijs library.

```javascript
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=..."
```

--------------------------------

### Add a new lead with ViciJS

Source: https://context7.com/thornebridge/vicijs/llms.txt

Use this to add a new lead to the system. Supports DNC checks, duplicate checks, and callback scheduling.

```typescript
import { ViciAdmin } from '@thornebridge/vicijs';

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

// Add a new lead
const result = await admin.leads.add({
  phoneNumber: '5551234567',
  listId: 101,
  firstName: 'John',
  lastName: 'Doe',
  email: 'john@example.com',
  dncCheck: 'Y',
  campaignDncCheck: 'Y',
  duplicateCheck: 'DUPLIST',
  addToHopper: 'Y',
  hopperPriority: 50,
  // Callback scheduling
  callback: 'Y',
  callbackDatetime: '2025-02-01 14:00:00',
  callbackType: 'USERONLY',
  callbackComments: 'Follow up on quote',
});
```