PHPackages                             masterfermin02/vicidial-api-wrapper - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. masterfermin02/vicidial-api-wrapper

ActiveLibrary[API Development](/categories/api)

masterfermin02/vicidial-api-wrapper
===================================

Beautiful and simple Implementation to integrate Vicidial API

4.0.1(3mo ago)27697↑100%14BSD-3-ClausePHPPHP ^8.2

Since Mar 3Pushed 3mo ago3 watchersCompare

[ Source](https://github.com/masterfermin02/vicidial-api-wrapper)[ Packagist](https://packagist.org/packages/masterfermin02/vicidial-api-wrapper)[ Docs](https://github.com/masterfermin02/vicidial-api-wrapper)[ RSS](/packages/masterfermin02-vicidial-api-wrapper/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (10)Dependencies (18)Versions (16)Used By (0)

Vicidial API PHP WRAPPER
========================

[](#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.

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/NON-AGENT_API.txt)
- [http://vicidial.org/docs/AGENT\_API.txt](http://vicidial.org/docs/AGENT_API.txt)

Install
-------

[](#install)

Requires PHP 8.2

`composer require masterfermin02/vicidial-api-wrapper`

### For PHP 7.4+ must install this version

[](#for-php-74-must-install-this-version)

`composer require masterfermin02/vicidial-api-wrapper:1.0.3`

What's New in v2.0 🎉
--------------------

[](#whats-new-in-v20-)

Version 4.0 introduces major improvements for a better developer experience:

### Configuration System

[](#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

[](#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](docs/RESPONSE_DTO.md) for details.

### Consistent Method Naming

[](#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](METHOD_NAMING_CONVENTIONS.md) for the complete guide.

### Reliability Features 🛡️ NEW

[](#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](RELIABILITY_FEATURES.md) for complete documentation.

```
// New way (v4.0+)
$config = VicidialConfig::create(
    host: 'vicidial.example.com',
    user: 'api_user',
    pass: 'api_password',
    protocol: 'https',
    timeout: 60
);
$client = VicidialClient::make($config);
```

See the [Migration Guide](MIGRATION.md) for upgrade instructions.

Authentication
--------------

[](#authentication)

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

### Recommended: Using VicidialConfig (v4.0+)

[](#recommended-using-vicidialconfig-v40)

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

[](#standard-authentication)

```
use VicidialApi\VicidialConfig;
use VicidialApi\VicidialClient;

$config = VicidialConfig::create(
    host: getenv('YOUR_VICIDIAL_IP'),
    user: getenv('YOUR_VICIDIAL_USER'),
    pass: getenv('YOUR_VICIDIAL_PASSWORD'),
    protocol: 'https',           // Optional: 'http' or 'https' (default: 'http')
    verifyTls: true,             // Optional: Verify TLS certificates (default: true)
    timeout: 30,                 // Optional: Request timeout in seconds (default: 30)
    urlEncodeDefault: false,     // Optional: URL encode by default (default: false)
    userAgent: 'MyApp/1.0',      // Optional: Custom user agent
    source: 'myapp'              // Optional: Source identifier (default: 'test')
);

$client = VicidialClient::make($config);
// or
$client = VicidialApi::client($config);
```

#### Basic Authentication (Remote Agent)

[](#basic-authentication-remote-agent)

```
use VicidialApi\VicidialConfig;
use VicidialApi\VicidialClient;

$config = VicidialConfig::createWithBasicAuth(
    host: getenv('YOUR_VICIDIAL_IP'),
    user: getenv('YOUR_VICIDIAL_USER'),
    pass: getenv('YOUR_VICIDIAL_PASSWORD'),
    basicAuthUser: getenv('YOUR_VICIDIAL_API_USER'),      // HTTP Basic Auth user
    basicAuthPass: getenv('YOUR_VICIDIAL_API_PASSWORD'),  // HTTP Basic Auth password
    protocol: 'https',
    timeout: 60
);

$client = VicidialClient::make($config);
```

### Response DTOs (New in v2.0)

[](#response-dtos-new-in-v20)

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

```
// New Response DTO methods (add "Response" suffix to any method)
$response = $client->agent()->updateFieldsResponse("gabriel", [
    'first_name' => 'John',
    'last_name' => 'Doe'
]);

// Built-in success checking - no regex needed!
if ($response->ok()) {
    echo "Success!";

    // Direct data access
    $leadId = $response->get('lead_id');

    // Multiple output formats
    $array = $response->asArray();
    $json = $response->toJson();
    $text = $response->asText();
}

// Original methods still work for backward compatibility
$rawString = $client->agent()->updateFields("gabriel", $fields);
```

See the [Response DTO Guide](RESPONSE_DTO.md) for complete documentation.

### Legacy: Factory Methods (Deprecated)

[](#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)

[](#standard-authentication-api-userpass)

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

```
$api = VicidialApi::create(
    getenv('YOUR_VICIDIAL_IP'),
    getenv('YOUR_VICIDIAL_USER'),
    getenv('YOUR_VICIDIAL_PASSWORD')
);
```

#### Basic Authentication (Remote Agent)

[](#basic-authentication-remote-agent-1)

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

```
$api = VicidialApi::createWithBasicAuth(
    getenv('YOUR_VICIDIAL_IP'),
    getenv('YOUR_VICIDIAL_API_USER'),      // HTTP Basic Auth user
    getenv('YOUR_VICIDIAL_API_PASSWORD'),   // HTTP Basic Auth password
    getenv('YOUR_VICIDIAL_REMOTE_AGENT'),   // Agent username
    getenv('YOUR_VICIDIAL_REMOTE_PASSWORD') // Agent password
);
```

How to use it
-------------

[](#how-to-use-it)

> 💡 **Tip**: See [example/using\_config.php](example/using_config.php) for a comprehensive demonstration of all configuration options.
>
> 📖 **Migrating from v1.x?** Check out the [Migration Guide](MIGRATION.md) for step-by-step instructions.

### Recommended Examples (Using VicidialConfig)

[](#recommended-examples-using-vicidialconfig)

#### Example: Complete workflow with configuration object

[](#example-complete-workflow-with-configuration-object)

```