Download the PHP package voicetel/voiceml without Composer

📞 VoiceML PHP SDK

The official PHP client for the VoiceML REST API — Twilio-compatible outbound voice and answering-machine-detection from VoiceTel, with modern PHP 8.1+ ergonomics and battle-tested Guzzle transport.

📚 Table of Contents

• Features
• Installation
• Quickstart
• Authentication
• Resource Reference
• Error Handling
• Pagination
• Migration from twilio-php
• Rate Limits
• Development
• API Documentation
• Contributors
• Sponsors
• License

✨ Features

🛡️ Modern PHP, Strictly Typed

• PHP 8.1+ end-to-end — readonly properties, named arguments, constructor property promotion, declare(strict_types=1) everywhere.
• Typed request and response models for every one of the 81 API operations across 9 resource families — Call->sid, Recording->duration, Queue->currentSize all hint cleanly in your IDE.
• Twilio-compatible wire shapes — AccountSid, From, To, status callbacks, pagination envelopes — match what Twilio's Programmable Voice API documents.
• PSR-4 autoloading under VoiceML\ — plays nicely with Symfony, Laravel, and every other Composer-aware framework.

🔁 Production-Grade Transport

• Built on Guzzle 7 (guzzlehttp/guzzle: ^7.8) — the de-facto HTTP client in the PHP ecosystem.
• Automatic retry with exponential backoff on 429 / 5xx — honors Retry-After headers.
• Configurable timeout per client (defaults to 30s) and configurable maxRetries (defaults to 2).
• HTTP Basic auth with AccountSid:ApiKey — exactly what the Twilio SDK uses, so existing credentials work unchanged.
• Structured exception hierarchy — RateLimitException, AuthenticationException, NotFoundException, etc. all subclasses of ApiException you can catch broadly or narrowly.

📞 Complete API Coverage

• Calls — originate, fetch, terminate, update + per-call recordings, streams, siprec, transcriptions, notifications, events, and the /Calls/{sid}/Payments lifecycle (Pay TwiML companion).
• Conferences — list, fetch, end conferences, plus participants (mute / hold / kick) and conference-scoped recordings.
• Queues — create, list, update, delete, peek, dequeue (front or specific member).
• Applications — CRUD on stored TwiML + callback bundles.
• Recordings — account-wide list, metadata fetch, audio fetch (follows S3 redirect), delete.
• Messages — create, fetch, list (To/From/DateSent filters + pagination), update (Body redaction; Status=canceled), delete.
• IncomingPhoneNumbers — list, fetch, update.
• Notifications — fetch, list.
• SIP — SIP Trunking: Domains (CRUD), CredentialLists + Credentials (CRUD), IpAccessControlLists + IpAddresses (CRUD), Domain↔ACL/CredentialList mappings (historical, Auth/Calls, Auth/Registrations namespaces).
• Routes V2 — Twilio Inbound Processing Region API: $client->routesV2->sipDomains->fetch($name) / update($name, voiceRegion: 'us1', friendlyName: 'ingress').
• Diagnostics — /health deep probe, OpenAPI spec.

🧪 Tested

• 110 unit tests with mocked Guzzle handlers — every method and every error path exercised, no network in CI.
• Conformance test suite that validates wire shapes against the published OpenAPI document — spec drift gets caught at parse time.

📦 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

🔑 Authentication

Every endpoint uses HTTP Basic with your AccountSid as the username and your per-tenant API key as the password — identical to Twilio's auth shape, so credentials issued for Twilio code work here unchanged.

For ports from the Twilio PHP SDK, the credential may be passed as authToken: instead of apiKey: — they are aliases:

Passing both raises ConfigurationException.

Don't have credentials yet? See voicetel.com/docs/api/v0.9/voiceml/ for issuance and rotation.

🌐 Per-product hosts

VoiceML mirrors Twilio's product-per-subdomain model. Most resources answer on the default host (voiceml.voicetel.com), but two products ride their own subdomains, derived automatically from your baseUrl:

• Conversations ($client->conversationsV1) → conversations.voicetel.com
• Messaging Service ($client->messagingV1) → messaging.voicetel.com

Derivation swaps the voiceml label for a recognised *.voicetel.com host (e.g. east-1.us.voiceml.voicetel.com → east-1.us.messaging.voicetel.com); any other base URL (a self-hosted instance) keeps every product on that single host. Self-hosters can point a product at a custom host explicitly:

🗺️ Resource Reference

Every method that takes a request body accepts a typed model imported from VoiceML\Model:

Recording audio

The audio fetch follows VoiceML's single 302→S3 redirect transparently:

If the recording is gone (no local file and no S3 key), GoneException is raised.

🚨 Error Handling

All HTTP errors extend VoiceML\Exception\ApiException, which extends VoiceML\Exception\VoiceMLException (a RuntimeException). Catch broadly or narrowly:

The Twilio-compatible error body (code, message, more_info, status) is parsed into $e->errorCode, $e->getMessage(), $e->moreInfo (also $e->getMoreInfo()), and $e->body.

📄 Pagination

List operations return a …List model with a Twilio-compatible pagination envelope (page, pageSize, total, nextPageUri, previousPageUri, …). For /Calls and /Messages, use the iterate() generator helper to walk all pages transparently:

For other resources, page manually with $client-><resource>->list(new ListXParams(page: $n)) and walk nextPageUri until null.

🔁 Migration from twilio-php

The accountSid + API token pair Twilio's SDK validates in its constructor works unchanged here:

Method names follow the resource map above ($client->calls->create(...), $client->queues->list(), …) rather than Twilio's $client->api->v2010->accounts($sid)->calls->create(...) chain — flatter, fewer keystrokes, same wire format on the way out. Request bodies are typed VoiceML\Model\… objects instead of associative arrays, so your IDE catches typos before runtime.

⏱️ Rate Limits

VoiceML applies per-tenant rate limits at the edge. 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/v0.9/voiceml/
• Validator: voicetel.com/voiceml/validator/
• SDK catalogue: voicetel.com/docs/voiceml-sdks/
• Type definitions: see the VoiceML\Model namespace — every wire shape has a typed PHP class.

🙌 Contributors

• Michael Mavroudis — Lead Developer

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

💖 Sponsors

📄 License

MIT with the Commons Clause restriction. See voicetel.com/legal/.