voipano / laravel
Official Laravel SDK for the Voipano Public Webservice API v1
Requires
- php: ^8.2
- illuminate/http: ^12.0 || ^13.0
- illuminate/routing: ^12.0 || ^13.0
- illuminate/support: ^12.0 || ^13.0
Requires (Dev)
- orchestra/testbench: ^10.0 || ^11.0
- phpunit/phpunit: ^11.5 || ^12.0 || ^13.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
راهنمای فارسی | Postman collection | Security
A Laravel package for the Voipano Public Webservice API v1, providing an easy-to-use facade, typed exceptions, and resource clients for all 23 requests in the official Postman collection (documentation version 2026.11.21).
Requirements
- PHP 8.2+; PHP 8.2 receives security fixes only until 31 December 2026. Prefer PHP 8.3+ for new projects.
- Laravel 12 on PHP 8.2+ or Laravel 13 on PHP 8.3+.
- Composer 2.
Installation
After the Git repository has been tagged v1.0.0 and registered on Packagist:
composer require voipano/laravel:^1.0
Laravel automatically discovers the service provider. Set the API token in your application's .env:
VOIPANO_API_TOKEN=your-private-token # Optional if the token is not bound to a single service: VOIPANO_SERVICE_ID=
Nothing else is needed for outgoing API calls. To customize timeouts, the endpoint, or inbound webhooks, publish the configuration:
php artisan vendor:publish --tag=voipano-config
Optional environment variables: VOIPANO_BASE_URL (default https://voipano.com/api/v1/webservice), VOIPANO_TIMEOUT (default 30) and VOIPANO_CONNECT_TIMEOUT (default 10). Never commit the .env file.
Basic usage
use Voipano\Laravel\Facades\Voipano; $services = Voipano::services()->all(); $contacts = Voipano::contacts()->all(['search' => 'Ali', 'page' => 1, 'per_page' => 20]); $contact = Voipano::contacts()->find('contact-id'); Voipano::contacts()->create([ 'primary_number' => '09120000000', 'first_name' => 'Ali', ]); Voipano::contacts()->update('contact-id', ['first_name' => 'Ali']); // These methods place REAL calls. Call them only from authorized application flows. // Voipano::calls()->otp('09120000000', ['purpose' => 'login']); // Voipano::calls()->clickToCall('09120000000', '09350000000', ['timeout' => 30]); // Voipano::calls()->secureCall('09120000000', '09350000000', ['retry_count' => 0]);
For multiple services or tenants, use immutable scoped clients; the global configuration is unaffected:
$client = Voipano::withToken($customerToken)->forService($serviceId); $reports = $client->callReports()->all(['page' => 1]); $traced = $client->withRequestId('my-request-id')->services()->all();
Resources
| Client | Methods |
|---|---|
services() |
all() |
contacts() |
all($filters), find($id), create($data), update($id, $data), updatePut($id, $data), delete($id), bulkImport($contacts, $options) |
contactGroups() |
all($filters), create($data), delete($id) |
musicOnHolds() |
all($filters) |
callReports() |
all($filters) |
voicemailInboxes() |
all($filters) |
recordings() |
call($cdrId, $recordId, $query), downloadCall($cdrId, $recordId, $destination, $query), voicemail($id, $context, $mailbox, $query), downloadVoicemail($id, $context, $mailbox, $destination, $query) |
webhooks() |
get(), configure($settings), route($event, $settings), configureLegacy($settings) |
calls() |
otp($phone, $options), clickToCall($source, $destination, $options), secureCall($source, $destination, $options) |
Each JSON endpoint returns the API's JSON decoded to a PHP array (no speculative response model). HTTP 204/empty responses return [].
Recordings
To download directly to a new file, rather than buffering the audio in memory:
$path = Voipano::recordings()->downloadCall( 'cdr-id', 'call-details-record-id', storage_path('app/private/call.wav') ); $path = Voipano::recordings()->downloadVoicemail( 'vm-id', 'default', '1001', storage_path('app/private/message.wav') );
The parent directory must exist, and the destination must not already exist. Save recordings outside the public web root. The Postman example contains distinct cdr_id and call_details_record_id values despite describing the latter as the same ID; both are required in this SDK until the server contract is confirmed.
Outgoing webhook setup
Voipano::webhooks()->configure([ 'endpoint_url' => 'https://example.org/webhooks/voipano', 'secret' => $secret, 'is_active' => true, ]); Voipano::webhooks()->route('missed_call', [ 'endpoint_url' => 'https://example.org/webhooks/voipano/missed', 'is_active' => true, ]);
Available event-specific routes: ringing, hangup, missed_call, and call_details_record.
Incoming webhook receiver
The Postman collection does not specify how Voipano signs incoming webhook requests. For security, no inbound route is registered by default; the built-in RejectAllVerifier rejects every request even if enabled.
Once the signing protocol is verified against the server implementation, implement Voipano\Laravel\Webhooks\Verifier, configure its class under voipano.webhooks.verifier, and then configure:
VOIPANO_WEBHOOK_RECEIVER_ENABLED=true VOIPANO_WEBHOOK_SECRET=your-verified-shared-secret
The default route is POST /webhooks/voipano; valid JSON object payloads that pass verification dispatch Voipano\Laravel\Webhooks\WebhookReceived. Do not use an accept-all verifier or turn on inbound webhooks until authentication and replay checks have been implemented and tested.
Errors and reliability
use Voipano\Laravel\Exceptions\ValidationException; try { Voipano::contacts()->create(['primary_number' => '09120000000']); } catch (ValidationException $e) { // $e->statusCode, $e->requestId, $e->errors }
AuthenticationException (401), PermissionException (403), NotFoundException (404), ValidationException (422), RateLimitException (429), and ServerException (5xx) inherit from ApiException. Transport and unexpected response errors have separate exception types.
The client generates an X-Request-Id and sends X-Webservice-Service-Id when selected. HTTP redirects and automatic retries are disabled. In particular, call and OTP operations must not be retried blindly: the documentation does not guarantee that client_ref prevents duplicate actions.
Tests
composer install
composer validate --strict --no-check-publish
composer test
Tests use faked HTTP requests and do not initiate real calls. The GitHub Actions matrix covers PHP 8.2–8.5 with compatible Laravel 12/13 versions. Review the real API's response schemas, limits, webhook signature protocol, and recording identifiers before relying on unverified behavior. The supplied Postman collection contains no example responses.
License
MIT. See LICENSE.