Download the PHP package masterfermin02/vicidial-api-wrapper without Composer

Vicidial API PHP WRAPPER

Beautiful and simple Implementation to integrate Vicidial API

DISCLAIMER: VICIdial is a registered trademark of the Vicidial Group which i am not related in anyway.

VICIDIAL is a software suite that is designed to interact with the Asterisk Open-Source PBX Phone system to act as a complete inbound/outbound contact center suite with inbound email support as well.

http://www.vicidial.org/vicidial.php

Vicidial has an AGENT API and NON AGENT API, this classes are intended to make it easier to use in PHP

• http://vicidial.org/docs/NON-AGENT_API.txt
• http://vicidial.org/docs/AGENT_API.txt

Install

Requires PHP 8.2

composer require masterfermin02/vicidial-api-wrapper

For PHP 7.4+ must install this version

composer require masterfermin02/vicidial-api-wrapper:1.0.3

What's New in v2.0 🎉

Version 4.0 introduces major improvements for a better developer experience:

Configuration System

• VicidialConfig: A clean configuration object with named parameters
• VicidialClient: The new recommended client entrypoint
• Full configuration control: Set protocol (HTTP/HTTPS), timeout, TLS verification, custom user agent, and more
• Better validation: Built-in validation for configuration values
• Backward compatible: Legacy factory methods still work (but are deprecated)

Response DTOs ✨ NEW

• Structured responses: No more regex or manual string parsing
• Helper methods: ok(), failed(), asArray(), asText(), toJson()
• Type-safe: Full IDE autocomplete and type checking
• Auto-parsing: Handles JSON, key-value, pipe-delimited, and other formats automatically
• Request tracking: Optional request ID for debugging
• Opt-in: Original methods still work, upgrade at your own pace

See the Response DTO Guide for details.

Consistent Method Naming

• camelCase everywhere: All methods use standard PHP camelCase convention
• Predictable patterns: addLead(), updateFields(), mohList(), pauseCode()
• No snake_case: Legacy Vicidial API's external_dial becomes dial(), pause_code becomes pauseCode()

See the Method Naming Conventions for the complete guide.

Reliability Features 🛡️ NEW

• Configurable timeouts: Separate connect timeout and request timeout
• Automatic retries: Exponential backoff with jitter for transient failures (5xx, network errors, rate limits)
• PSR-3 logging: Pluggable logger for observability and debugging
• Sensitive data protection: Automatic redaction of passwords and API keys in logs
• Production-ready defaults: Sensible timeout and retry configurations out of the box

See the Reliability Features Guide for complete documentation.

See the Migration Guide for upgrade instructions.

Authentication

This wrapper supports two authentication modes and provides both a modern configuration-based approach and legacy factory methods.

Recommended: Using VicidialConfig (v4.0+)

The recommended way to create a client is using the VicidialConfig object, which provides a clean, explicit way to configure all client options:

Standard Authentication

Basic Authentication (Remote Agent)

Response DTOs (New in v2.0)

All API methods now have Response DTO variants that return structured response objects instead of raw strings:

See the Response DTO Guide for complete documentation.

Legacy: Factory Methods (Deprecated)

The original factory methods are still supported for backward compatibility but are deprecated in favor of the configuration object.

Standard Authentication (API User/Pass)

Use VicidialApi::create() for standard API authentication with user credentials. This is the most common method for Agent and Admin API operations.

Basic Authentication (Remote Agent)

Use VicidialApi::createWithBasicAuth() for remote agent operations that require HTTP Basic Authentication along with agent credentials.

How to use it

💡 Tip: See example/using_config.php for a comprehensive demonstration of all configuration options.

📖 Migrating from v1.x? Check out the Migration Guide for step-by-step instructions.

Recommended Examples (Using VicidialConfig)

Example: Complete workflow with configuration object

Example: Production setup with reliability features

See example/reliability_features.php for more examples.

#### Example: Remote agent with Basic Authentication

---

### Legacy Examples (Deprecated)

> **Note**: The following examples use the legacy factory methods. While still supported, we recommend using `VicidialConfig` and `VicidialClient` as shown above.

### Example 1: Update fields on agent screen

### Example 2: Hangup Call, Dispo it and Pause Agent

### Example 3: Make an external dial call

### Example 4: Using the Admin API (Non-Agent API)

### Example 5: Using URL encode for special characters

### Example 6: Remote agent login with Basic Authentication

### Docs:
- [Agent](https://github.com/masterfermin02/vicidial-api-wrapper/blob/main/docs/agent.md)
- [Admin](https://github.com/masterfermin02/vicidial-api-wrapper/blob/main/docs/admin.md)
- [Response DTO Guide](https://github.com/masterfermin02/vicidial-api-wrapper/blob/main/RESPONSE_DTO.md)
- [Method Naming Conventions](https://github.com/masterfermin02/vicidial-api-wrapper/blob/main/METHOD_NAMING_CONVENTIONS.md)
- [Error Handling Guide](https://github.com/masterfermin02/vicidial-api-wrapper/blob/main/docs/ERROR_HANDLING.md) 🎯 **NEW**
- [Reliability Features](https://github.com/masterfermin02/vicidial-api-wrapper/blob/main/RELIABILITY_FEATURES.md) 🛡️ **NEW**