Download the PHP package voicetel/sdk without Composer

📞 VoiceTel PHP SDK

The official PHP client for the VoiceTel REST API — provision numbers, place orders, validate e911, send messages, and manage your account, with modern PHP 8.1+ ergonomics and battle-tested Guzzle transport.

📚 Table of Contents

• Features
• Installation
• Quickstart
• Authentication
• Resource Reference
• Error Handling
• Rate Limits
• Development
• API Documentation
• Contributors
• Sponsors
• License

✨ Features

🛡️ Modern PHP, Strictly Typed

• PHP 8.1+ end-to-end — readonly properties, native enums, named arguments, typed everywhere.
• ErrorKind enum for HTTP error classification: BadRequest, Authentication, PermissionDenied, NotFound, Conflict, RateLimit, Server, Unknown.
• PSR-4 autoloading under VoiceTel\Sdk\, plays nicely with Symfony, Laravel, and every other Composer-aware framework.
• PHPStan level 8 clean across the entire src/ tree.

🔁 Production-Grade Transport

• Built on Guzzle 7 — the de-facto HTTP client in the PHP ecosystem.
• Automatic retry with exponential backoff on 429 / 5xx — honors Retry-After headers, capped at 8s.
• Configurable timeout per client (defaults to 30s).
• Bearer auth managed for you; the password → key exchange is one method call ($client->login(...)).
• Structured ApiError with typed kind so you can match ($e->kind) { ErrorKind::RateLimit => ... } without parsing HTTP status codes.
• Envelope-aware — strips the {"status":"success","data": ...} wrapper before returning the inner payload.

📞 Complete API Coverage (73 operations)

• Numbers — list, get, add, remove, route, translate, CNAM, LIDB, fax, forward, SMS, messaging campaigns, port-out PIN, account moves.
• Account — profile, sub-accounts, CDRs, credits, payments, MRC, registration, password recovery.
• e911 — record provisioning, address validation, lookup, removal.
• Gateways — list, create, update, delete, view bound numbers.
• Messaging — SMS & MMS sending, message history, 10DLC brand and campaign registration, per-number messaging state.
• Lookups — CNAM and LRN dips.
• iNumbering — inventory search, coverage queries, number orders, port-in submissions, port-out availability checks.
• Support — ticket create / read / update / delete, threaded messages, replies.
• ACL — IP allowlist management with structured 409 conflict bodies.
• Authentication — switch between Digest, IP-only, or hybrid modes; rotate passwords.

🧪 Battle-Tested

• 101 unit tests at 94%+ line coverage with PHPUnit 10.
• Mocked Guzzle via GuzzleHttp\Handler\MockHandler — every method and every error path exercised, no network in CI.
• Read-only integration scaffolding gated by VOICETEL_USERNAME / VOICETEL_PASSWORD env vars.

📦 Clean Distribution

• Zero codegen footprint — every byte hand-written.
• Single Composer package, single namespace, no surprise transitive deps beyond Guzzle.

🚀 Installation

Requires PHP 8.1 or later and the json extension (bundled with PHP).

🏁 Quickstart

Or, if you already have an API key, skip login() and pass it straight to the constructor:

🔑 Authentication

Every endpoint requires Authorization: Bearer <apikey> except POST /v2.2/account/api-key, which exchanges username + password for a fresh key. $client->login() handles the exchange and installs the returned key on the client.

Re-fetch the API key after any password change — the old one is invalidated.

Don't have credentials yet? Get them at voicetel.com/docs/api/v2.2/credentials.

🗺️ Resource Reference

Notes on payload shape

• messaging->send() uses the wire field names fromNumber and toNumber — pass them exactly as shown.
• support->create() / support->get() return a conversation whose number field is a ticket sequence integer (e.g. 1015), not a phone number — keep that distinction in mind everywhere else in this API where number is a 10-digit TN.
• LIDB endpoints (numbers->setLidb()) use the spelling Lidb consistently — the legacy Libd typo from earlier spec drafts has been corrected.
• iNumbering->portAvailability() includes the v2.2.10 fields localRoutingNumber and rateCenterTier alongside the original number, portable, losingCarrier, and reason.
• DELETE endpoints generally return 204 No Content — the corresponding methods return void. Three endpoints intentionally return a body and an array: acl->remove(), numbers->unassignCampaign(), and numbers->bulkUnassignCampaign().

🚨 Error Handling

All HTTP errors throw VoiceTel\Sdk\ApiError. Inspect kind, statusCode, code(), or body:

Or use the helper predicates:

⏱️ Rate Limits

These endpoints are limited to 6 requests per hour per IP:

• account/info ($client->account->get())
• account/cdr
• account/recurring-charges
• account/payments
• account/registration
• account/api-key ($client->login())

The SDK automatically retries 429 responses with Retry-After honored, up to maxRetries (default 2). To bump it:

🛠️ Development

📖 API Documentation

• Reference docs: voicetel.com/docs/api/v2.2/
• Interactive playground: voicetel.com/docs/api/v2.2/playground/ — try the API in your browser without writing any code
• API credentials: voicetel.com/docs/api/v2.2/credentials/

🙌 Contributors

• Michael Mavroudis — Lead Developer

Contributions welcome. Open an issue describing the change, or send a pull request against main.

💖 Sponsors

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.