PHP client for DIDWW API v3.
The DIDWW API provides a simple yet powerful interface that allows you to fully integrate your own applications with DIDWW services. An extensive set of actions may be performed using this API, such as ordering and configuring phone numbers, setting capacity, creating SIP trunks and retrieving CDRs and other operational data.
The DIDWW API v3 is a fully compliant implementation of the JSON API specification.
This SDK uses swisnl/json-api-client for JSON:API serialization and deserialization.
Read more https://doc.didww.com/api
This SDK targets DIDWW API version 2026-11-19 (Didww\Credentials::DEFAULT_API_VERSION). The version is not sent as a header: it is requested in the api_version of every access token the SDK mints (see Authentication).
| Package Version | Branch | DIDWW API Version |
|---|---|---|
| 11.x | master |
2026-11-19 |
| 10.x | release-10 |
2026-04-16 |
| 9.x | 2022-05-10 |
2022-05-10 |
A later version can be requested through Credentials or the apiVersion argument of Configuration::configure(). A value that is not a YYYY-MM-DD date, or a version earlier than 2026-11-19, throws an \InvalidArgumentException. The resources of earlier API versions are not in this package: use 10.x from the release-10 branch for API 2026-04-16 (see Migrating from 10.x).
- PHP 8.2+
- Guzzle 8 (
guzzlehttp/guzzle^8.0.1) - Extensions:
ext-curl,ext-json,ext-openssl,ext-zlib - Recommended under PHP-FPM or mod_php:
ext-apcu, so that web requests share access tokens (see Token cache) - Optional:
psr/simple-cacheand a PSR-16 cache implementation, to share access tokens between servers
composer require didww/didww-api-3-php-sdk:^11For API 2026-04-16, stay on 10.x: composer require didww/didww-api-3-php-sdk:^10.2.
$credentials = new Didww\Credentials('YOUR_API_KEY', 'sandbox');
Didww\Configuration::configure($credentials);
// Check balance
$balance = Didww\Item\Balance::find()->getData();
echo "Balance: " . $balance->getTotalBalance();
// List DID groups with stock keeping units
$didGroups = Didww\Item\DidGroup::all([
'include' => 'stock_keeping_units',
'filter' => ['area_name' => 'Acapulco'],
])->getData();For more examples visit examples/.
For details on obtaining your API key please visit https://doc.didww.com/api3/configuration.html
- Source code: examples/
- How to run: examples/README.md
use Didww\Auth\Scope;
// Production
$credentials = new Didww\Credentials('YOUR_API_KEY', 'production');
Didww\Configuration::configure($credentials);
// Sandbox, read-only tokens, a PSR-3 logger and a proxy
$credentials = new Didww\Credentials('YOUR_API_KEY', 'sandbox');
Didww\Configuration::configure(
$credentials,
['proxy' => 'http://proxy.example.com:8080'],
scope: Scope::READ,
logger: $logger, // any Psr\Log\LoggerInterface, e.g. Monolog
);Credentials takes the API key, the environment and, optionally, the API version and the scope: new Didww\Credentials($apiKey, $env, $version = null, $scope = null). Configuration::configure() takes the credentials, the Guzzle configuration and the named arguments below. The configuration is static: the last configure() call applies to the whole process.
| Argument | Default | Description |
|---|---|---|
$credentials |
required | new Didww\Credentials($apiKey, 'production') or 'sandbox'. The environment selects the API, token service and price hosts. See Environments. |
$httpClientConfig |
[] |
Guzzle configuration, used on top of the SDK defaults. See HTTP client. |
apiVersion: |
the version of $credentials (Credentials::DEFAULT_API_VERSION) |
API version requested in every token. See API Version. |
scope: |
the scope of $credentials (none) |
Didww\Auth\Scope::READ, Scope::FULL, 'read' or 'full'. Without a scope none is requested and the token service grants full. See Scope. |
tokenStore: |
ApcuTokenStore where APCu is enabled outside the CLI, otherwise an in-memory store shared by the process |
A Didww\Auth\TokenStore. See Token cache. |
logger: |
Psr\Log\NullLogger |
PSR-3 logger for the token warnings and debug messages. See Logging. |
baseUrl: |
API URL of the environment | JSON:API base URL, with or without /v3. |
authUrl: |
Token service of the environment | Token service base URL. |
voiceInPricesUrl:, voiceOutPricesUrl:, smsPricesUrl: |
Price hosts of the environment | Price service base URLs, with or without /v3. |
The API key is sent only to the token service. An overridden URL, for example to send the traffic through a proxy, does not change the token audiences (see Authentication).
new Credentials(...) and Configuration::configure() throw an \InvalidArgumentException, before any request, for:
- an empty API key, or one with a character that cannot be sent in an HTTP header (a control character other than tab, such as a trailing newline, or a byte outside ASCII, such as a non-breaking space);
- an environment other than
productionandsandbox(use the URL arguments ofconfigure()for other hosts); - an API version that is not a
YYYY-MM-DDdate, or that is earlier than2026-11-19; - a scope other than
readandfull; - a base, token service or prices URL that is not an http or https URL with a host, or that has a query or fragment.
| Environment | API | Token service | Voice IN prices | Voice OUT prices | SMS prices |
|---|---|---|---|---|---|
production |
https://api.didww.com/v3 |
https://auth.didww.com |
https://api-vin.didww.com/v3 |
https://api-vout.didww.com/v3 |
https://api-sms.didww.com/v3 |
sandbox |
https://sandbox-api.didww.com/v3 |
https://auth-sandbox.didww.com |
https://api-vin-sandbox.didww.com/v3 |
https://api-vout-sandbox.didww.com/v3 |
https://api-sms-sandbox.didww.com/v3 |
A firewall that limits outgoing traffic must allow the token service, and the price hosts when you use Prices.
Every call goes through Guzzle, built from $httpClientConfig on top of these defaults. The one exception is SupportingDocumentTemplate::download(), which fetches the public template file with plain curl, without this configuration, the token or the API key, and follows redirects.
| Option | Default | Meaning |
|---|---|---|
connect_timeout |
10 |
Seconds to connect. |
read_timeout |
60 |
Seconds the connection may sit silent (connecting, waiting for the response, reading the body), applied only by Guzzle's stream handler. With the default curl handler a stalled transfer is ended by the stall limit. |
| curl stall limit | 1 byte/s over 60 s | A transfer that receives less than 1 byte/s for 60 s, the wait for the response included, is aborted (CURLOPT_LOW_SPEED_LIMIT / CURLOPT_LOW_SPEED_TIME). Not sent to Guzzle's stream handler, which rejects curl options; read_timeout covers a stall there. |
timeout |
none | No total timeout, so a large price or export file is not cut off. |
allow_redirects |
false |
Redirects are never followed. |
decode_content |
false |
Responses are not decompressed; price and export files are written as served. |
cookies |
false |
No cookies are stored or sent. |
Your keys replace the defaults. curl options are merged with the stall limit (your CURLOPT_LOW_SPEED_* win); Guzzle's stream handler rejects any curl options you pass. headers are kept, except If-None-Match, and a User-Agent is added unless you set one. An on_headers or on_stats callback you pass also runs for export and price file downloads, after the SDK's own. A handler you pass is wrapped by the SDK, so its middleware runs for every call: the token service, the JSON:API, export download, encrypted file upload and prices. That middleware sees the Authorization header, and the Api-Key header of token requests: do not log them.
Didww\Configuration::configure($credentials, [
'proxy' => 'http://proxy.example.com:8080',
'verify' => '/etc/ssl/certs/ca-certificates.crt',
'connect_timeout' => 5,
]);- Redirects. Requests made through the SDK's Guzzle client are never redirected, whatever
allow_redirectssays, so that a token or the API key is not sent to another URL. - Total timeout. A
timeoutyou set also bounds the download of a large price or export file. Preferconnect_timeoutand the stall limit (CURLOPT_LOW_SPEED_TIME). A price lookup takes at most 60 s, or yourtimeoutwhen it is shorter. - Token requests use the same handler and options, with a 10 s connect and total timeout per attempt.
Configuration::getHttpClient() returns the Guzzle client of the SDK, which adds the bearer token to every request except those to public_keys (pass the BearerMiddleware::AUDIENCE_OPTION request option as false for none). After a 401 it mints a new token and sends the request once more only when the body is empty or seekable and the sink is none, a path, a seekable resource written at its end (cut back to that size), a seekable stream written at its end that the 401 was not written to, or another stream the 401 was not written to; otherwise the 401 is returned.
Every request carries Authorization: Bearer <token>. The SDK mints the tokens itself with POST /token on the token service, sending your API key in the Api-Key header. The API key is sent nowhere else. No code change is needed for this: new Didww\Credentials('YOUR_API_KEY', 'production') works as before.
-
Audience. One token per audience, minted on the first call to a service and reused until it expires. The audience is the production hostname of the service, in the sandbox too:
Calls Token audience JSON:API resources, export download, encrypted file upload api.didww.comVoice IN prices api-vin.didww.comVoice OUT prices api-vout.didww.comSMS OUT (A2P, P2P, OTP) and SMS IN prices api-sms.didww.comDidww\Item\PublicKey::all()is sent without a token. -
Expiry and 401. The SDK asks for the longest lifetime the token service grants, one hour (
expires_in: 3600), and caches a token for theexpires_ingranted, with no local expiry margin. When a request is answered 401, the SDK drops that token, mints a new one and sends the request once more. A second 401 drops the new token too and becomes the result of the call (see Error Handling). A 403, such asinsufficient_scope, is never retried. -
Token service errors throw a
Didww\Exception\DidwwAuthExceptionfrom any call that needs a new token (kinds in Error Handling):- A 429 throws
AuthErrorKind::RATE_LIMITEDwithgetRetryAfter()(theRetry-Afterseconds, at least 1). Every further token request for the same token service and API key in the process (under PHP-FPM or mod_php: in the same web request) fails the same way without a request until that time has passed, plus a small random delay so that clients do not retry in step. Such a refusal reports the seconds still left, so retry in a loop rather than once. - A 5xx answer, a connection failure or a timeout is retried with exponential backoff and full jitter (0.5 s base, 8 s cap, 4 attempts in all), then throws
AuthErrorKind::SERVER_ERRORorAuthErrorKind::CONNECTION_ERROR. - A 400, a 401 or a TLS failure is thrown at once, without a retry.
- A 429 throws
use Didww\Auth\Scope;
new Didww\Credentials('YOUR_API_KEY', 'production', scope: Scope::READ); // GET and HEAD only
new Didww\Credentials('YOUR_API_KEY', 'production', scope: Scope::FULL);
new Didww\Credentials('YOUR_API_KEY', 'production'); // the default: no scope is requested, the token service grants full
// Or when configuring
Didww\Configuration::configure($credentials, scope: Scope::READ);A read token is enough for the price lookups and price files. A write with a read token is answered 403, which the JSON:API resources return as document errors (see Error Handling).
The SDK compares each token it receives with what it asked for:
- a different
scope(for examplefullgranted for areadrequest) or a differentapi_versionis logged as a warning (see Logging), and the token is used; - a token with an empty access token, or whose
auddoes not include the requested audience, throwsAuthErrorKind::INVALID_GRANTand is not cached.
Tokens are cached in a Didww\Auth\TokenStore, keyed by the token service URL, the API key (as a SHA-256 hash), the audience, the API version and the scope. Each entry is stored for the token's expires_in.
Every configure() call of the process without its own store shares one default store:
- Outside the CLI (PHP-FPM, mod_php and other web servers) with APCu enabled:
Didww\Auth\ApcuTokenStore. APCu is shared by the workers of the server, so a web request reuses the tokens minted by earlier ones. - Otherwise:
Didww\Auth\MemoryTokenStore, in process memory. A long-running worker (a queue consumer, a daemon, a CLI job) reuses its tokens. Under PHP-FPM or mod_php without APCu the process memory lasts one request, so every request mints new tokens: enable APCu, or pass a store that outlives the request.
APCu memory is shared by every pool of one PHP-FPM master. Where the sites of other owners run under the same master, as on shared hosting, pass tokenStore: new Didww\Auth\MemoryTokenStore() or a store of your own. To share tokens between servers, use Didww\Auth\Psr16TokenStore over a PSR-16 cache (requires psr/simple-cache):
use Symfony\Component\Cache\Adapter\RedisAdapter;
use Symfony\Component\Cache\Psr16Cache;
// Redis, with short timeouts
$cache = new Psr16Cache(new RedisAdapter(
RedisAdapter::createConnection('redis://localhost', ['timeout' => 2, 'read_timeout' => 2]),
));
Didww\Configuration::configure($credentials, tokenStore: new Didww\Auth\Psr16TokenStore($cache));Psr16TokenStore stores tokens as arrays under keys that fit the PSR-16 key rules. To use another storage, implement the interface:
interface TokenStore
{
public function get(string $key): ?AccessToken;
public function set(string $key, AccessToken $token, int $ttl): void; // a ttl of 0 or less means no expiry
public function delete(string $key): void;
}AccessToken::toArray() and AccessToken::fromArray() hold every field under its wire name, the access token included, so that a store can persist it; var_dump(), print_r() and the string form of an AccessToken never show the access token. A shared store holds live bearer tokens, so protect it like the API key. Processes that share a store can each mint once when a token is missing. A store that throws does not fail the call: the error is logged as a warning, and the call goes on with a newly minted token. The SDK cannot interrupt a store call that hangs, so bound the store's own I/O (as with the Redis timeouts above).
The logger: argument takes any PSR-3 Psr\Log\LoggerInterface. Following the PHP library convention, the default is Psr\Log\NullLogger: nothing is logged, not even the mismatch warnings, until you pass a logger.
- Warnings:
DIDWW token scope mismatchandDIDWW token api_version mismatch(withrequestedandgrantedin the context), and token store failures (DIDWW token store read failed,write failed,delete failed). - Debug:
DIDWW token minted, withaud,scope,api_version,expires_inandduration_ms.
Neither the token nor the API key is ever logged. A logger that throws does not fail the call.
The SDK keeps the API key and the tokens out of the exceptions it throws (their messages, requests and chained exceptions) and marks its own parameters that carry them #[\SensitiveParameter], which PHP 8.2+ hides in stack traces. Other stack frames of an HTTP call (in Guzzle, the JSON:API client or your middleware) can hold the request objects, which carry the Authorization header or the Api-Key header of a token request. Run production with zend.exception_ignore_args = On (the php.ini-production value), so that exception traces keep no arguments, and do not log or report traces with arguments.
- Audience strategy. One token per audience, minted on first use, rather than one token naming every service. An account that never calls the prices services never requests their audiences, so a refused audience cannot break DID management, and every token is valid for one service only.
- Cache store. APCu by default where it is enabled outside the CLI, so that the requests of PHP-FPM or mod_php workers share tokens; otherwise in-process memory, shared by the whole process because the SDK configuration is static. A store shared between servers is opt-in through
tokenStore:. - Token lifetime. The longest the token service grants, one hour, so that a process mints each token as rarely as possible. Lifetime is decided by the server through the 401 refresh, not by a local expiry margin.
- Logger. PSR-3, silent by default (
NullLogger), as PHP libraries usually are. - HTTP defaults. Connect and read timeouts and a stall limit instead of a total timeout, so that large files are not cut off; no redirects, so that credentials stay on the configured hosts; no decompression, so that files are written as served; no cookies, so that no state is carried between calls.
- Gzip handling. Price files and export files are written to your path or stream exactly as served, still gzipped, without being held in memory. The SDK never decompresses a price file on its own:
Didww\Prices\PriceFileReaderreads a downloaded file when you want rows, andExport::downloadAndDecompress()writes an export as plain CSV. - Upload retry. The 401 retry sends the request body a second time.
EncryptedFile::upload()takes the encrypted content as a string and builds the multipart body in memory, so the retry always resends the complete body. - Blocking waits. PHP calls are synchronous: the token backoff and the price file 503 retry wait in the calling process. Run price file downloads from the command line or a scheduled job (cron), not within a web request.
use Didww\Enum\NumberType;
// Countries
$countries = Didww\Item\Country::all()->getData();
$country = Didww\Item\Country::find('uuid')->getData();
// Regions
$regions = Didww\Item\Region::all()->getData();
// Cities
$cities = Didww\Item\City::all()->getData();
// Areas
$areas = Didww\Item\Area::all()->getData();
// NANPA Prefixes
$prefixes = Didww\Item\NanpaPrefix::all()->getData();
// DID Groups (with stock keeping units), filtered by number type
$groups = Didww\Item\DidGroup::all([
'include' => 'stock_keeping_units',
'filter' => ['number_type' => NumberType::TOLL_FREE->value],
])->getData();
// Available DIDs
$available = Didww\Item\AvailableDid::all([
'include' => 'did_group.stock_keeping_units',
])->getData();
// Proof Types
$proofTypes = Didww\Item\ProofType::all()->getData();
// Public Keys
$publicKeys = Didww\Item\PublicKey::all()->getData();
// Address Requirements
$requirements = Didww\Item\AddressRequirement::all()->getData();
// Balance (singleton)
$balance = Didww\Item\Balance::find()->getData();AddressRequirement::getPersonalMandatoryFields() and getBusinessMandatoryFields() list the identity fields that must be filled in, by the field names as the API spells them: birth_date, country, birth_country, id_number, personal_tax_id and contact_email for a personal identity, and id_number, tax_id, country, company_reg_number, personal_tax_id and contact_email for a business one. tax_id is the VAT number of the identity (Identity::getVatId()). Each list is empty when no field is mandatory, never null. EmergencyRequirement has the same getters, also by API field name, with its own lists: birth_date, country, id_number, personal_tax_id and contact_email for a personal identity, id_number, tax_id, country, company_reg_number, personal_tax_id, contact_email and birth_date for a business one, and getAddressMandatoryFields() with area.
DidGroup, AddressRequirement, EmergencyRequirement and EmergencyCallingService have getNumberType(), which returns a Didww\Enum\NumberType (LOCAL, NATIONAL, MOBILE, TOLL_FREE, SHARED_COST, GLOBAL), or the raw string for a value this SDK does not know. DidGroup::getIsDemo() flags demo groups.
// List DIDs
$dids = Didww\Item\Did::all()->getData();
// Update DID - assign trunk and capacity
$did = Didww\Item\Did::find('uuid')->getData();
$did->setDescription('Updated');
$did->setCapacityLimit(20);
$did->setVoiceInTrunk(Didww\Item\VoiceInTrunk::build('trunk-uuid'));
$did->save();A DID's inbound messages go to an SMS trunk or to an SMS trunk group. The two are exclusive: setSmsTrunk() sends sms_trunk_group as null in the same request, and setSmsTrunkGroup() sends sms_trunk as null, as setVoiceInTrunk() and setVoiceInTrunkGroup() do.
// sends sms_trunk and sms_trunk_group: null
$did = Didww\Item\Did::build('did-uuid');
$did->setSmsTrunk(Didww\Item\SmsTrunk::build('sms-trunk-uuid'));
$did->save();
// sends sms_trunk_group and sms_trunk: null
$did = Didww\Item\Did::build('did-uuid');
$did->setSmsTrunkGroup(Didww\Item\SmsTrunkGroup::build('sms-trunk-group-uuid'));
$did->save();
// unroute: sends sms_trunk: null and sms_trunk_group: null
$did = Didww\Item\Did::build('did-uuid');
$did->setSmsTrunk(null);
$did->setSmsTrunkGroup(null);
$did->save();
$dids = Didww\Item\Did::all([
'filter' => ['sms_trunk.id' => 'sms-trunk-uuid'],
'include' => 'sms_trunk,sms_trunk_group',
])->getData();
$trunk = $dids[0]->smsTrunk()->getIncluded(); // or ->smsTrunkGroup()->getIncluded()An SMS trunk cannot be deleted while DIDs are routed to it, nor an SMS trunk group while DIDs are routed to it or to one of its trunks: unroute those DIDs, or route them elsewhere, first.
When updating resources, the SDK tracks which attributes and relationships have changed since the resource was loaded (or built). Only dirty fields are included in the PATCH request body, reducing payload size and avoiding unintended overwrites.
// Load a DID from the API - all fields are marked as persisted
$did = Didww\Item\Did::find('uuid')->getData();
// Change only the description - only dirty fields are sent
$did->setDescription('New description');
$did = $did->save()->getData(); // reassign to get synced persisted state
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"description":"New description"}}}
// Build a resource by ID and set a single field
$did = Didww\Item\Did::build('uuid');
$did->setCapacityLimit(10);
$did = $did->save()->getData();
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"capacity_limit":10}}}
// Explicitly clear a field by setting it to null
$did = Didww\Item\Did::build('uuid');
$did->setDescription(null);
$did = $did->save()->getData();
// PATCH body: {"data":{"type":"dids","id":"...","attributes":{"description":null}}}
// Included resources also start with clean dirty state
$didDocument = Didww\Item\Did::find('uuid', ['include' => 'voice_in_trunk']);
$trunk = $didDocument->getData()->voiceInTrunk()->getIncluded();
// $trunk has persisted state synced - modifying and saving it sends only dirty fields
$trunk->setName('Renamed trunk');
$trunk = $trunk->save()->getData();
// PATCH body: {"data":{"type":"voice_in_trunks","id":"...","attributes":{"name":"Renamed trunk"}}}use Didww\Enum\CliFormat;
use Didww\Enum\Codec;
use Didww\Enum\IceMode;
use Didww\Enum\MediaEncryptionMode;
use Didww\Enum\SstRefreshMethod;
use Didww\Enum\TransportProtocol;
// Create SIP trunk
$sip = new Didww\Item\Configuration\Sip([
'host' => 'sip.example.com',
'port' => 5060,
'codecs' => [Codec::PCMA, Codec::PCMU, Codec::TELEPHONE_EVENT],
'ice_mode' => IceMode::ACCEPT,
'transport_protocol_id' => TransportProtocol::UDP,
'sst_refresh_method_id' => SstRefreshMethod::INVITE,
'media_encryption_mode' => MediaEncryptionMode::DISABLED,
'rerouting_disconnect_code_ids' => Didww\Item\Configuration\Base::getDefaultReroutingDisconnectCodeIds(),
]);
$trunk = new Didww\Item\VoiceInTrunk();
$trunk->setName('My SIP Trunk');
$trunk->setCliFormat(CliFormat::E164);
$trunk->setRingingTimeout(30);
$trunk->setConfiguration($sip);
$trunkDocument = $trunk->save();
$trunk = $trunkDocument->getData();
// Update trunk
$trunk->setDescription('Updated');
$trunk->save();
// Delete trunk
$trunk->delete();codecs lists the codecs offered on calls to the trunk by name, in priority order: the first has the highest priority. It replaces codec_ids; setCodecs() and the constructor take Didww\Enum\Codec cases or strings, and getCodecs() returns Codec cases (the raw string for a name this SDK does not know). Left out, the trunk offers pcmu, pcma, g729, g723 and telephone_event. ice_mode, rtcp_mux_mode and rtcp_feedback_mode take disabled (the default), accept or initiate (Didww\Enum\IceMode, RtcpMuxMode and RtcpFeedbackMode).
pop is a plain string attribute. getPop() returns a Didww\Enum\Pop (NYC, FRA, LAC, MIA, SG, HK, AMS: nyc, fra, lac, mia, sg, hk, ams), or the raw string for a value this SDK does not know; setPop() takes a Pop, a string, or null to let DIDWW choose. It is no longer a relationship and cannot be included.
$trunk = Didww\Item\VoiceInTrunk::find('trunk-uuid')->getData();
$trunk->setPop(Didww\Enum\Pop::AMS);
$trunk->save();A Voice In Trunk can also authenticate inbound calls via SIP registration credentials generated by DIDWW. The SDK auto-cascades the dependent fields the server requires:
setEnabledSipRegistration(true)clears any previously-sethost/port(the server rejects them with 422 otherwise);setHost(<non-null>)flipsenabled_sip_registrationtofalseand forcesuse_did_in_ruri = falseso the server accepts the disable PATCH.
The server generates incoming_auth_username and incoming_auth_password
and surfaces them in the response when SIP registration is enabled.
Constructor arrays bypass the cascade so server responses deserialize
as-is.
$sip = new Didww\Item\Configuration\Sip([
'enabled_sip_registration' => true,
'use_did_in_ruri' => true,
'cnam_lookup' => true,
]);
$trunk = new Didww\Item\VoiceInTrunk(['name' => 'Office (registered)', 'configuration' => $sip]);
$created = $trunk->save()->getData();
$config = $created->getConfiguration();
// $config->getIncomingAuthUsername() — server-generated
// $config->getIncomingAuthPassword() — server-generatedTo disable SIP registration on an existing trunk, just call setHost()
— the cascade flips enabled_sip_registration and use_did_in_ruri to
false automatically:
$disable = new Didww\Item\Configuration\Sip();
$disable->setHost('sip.example.com');
$update = new Didww\Item\VoiceInTrunk(['configuration' => $disable]);
$update->setId('trunk-uuid');
$update->save();$group = new Didww\Item\VoiceInTrunkGroup();
$group->name = 'Primary Group';
$group->capacity_limit = 50;
$groupDocument = $group->save();Deleting a trunk group also deletes the trunks in it. It is refused (422) while the group or one of its trunks is routed to a DID: route those DIDs elsewhere first.
Voice Out Trunks use a polymorphic authentication_method (2026-04-16). Three types are supported:
credentials_and_ip-- default method;usernameandpasswordare server-generated and returned in the response.twilio-- requires atwilio_account_sid.ip_only-- read-only; can only be configured by DIDWW staff upon request. Cannot be set via the API.
use Didww\Enum\OnCliMismatchAction;
use Didww\Enum\VoiceOutCodec;
use Didww\Item\AuthenticationMethod\CredentialsAndIp;
$trunk = new Didww\Item\VoiceOutTrunk();
$trunk->setName('My Outbound Trunk');
// NOTE: 203.0.113.0/24 is RFC 5737 TEST-NET-3 documentation space.
// Replace with the real CIDR of your SIP infrastructure.
$trunk->setAuthenticationMethod(new CredentialsAndIp([
'allowed_sip_ips' => ['203.0.113.0/24'],
]));
$trunk->setOnCliMismatchAction(OnCliMismatchAction::REPLACE_CLI);
$trunk->setCodecs([VoiceOutCodec::OPUS, VoiceOutCodec::PCMA, VoiceOutCodec::TELEPHONE_EVENT]);
$trunk->setDefaultDid(Didww\Item\Did::build('did-uuid'));
$trunkDocument = $trunk->save();
// $trunkDocument->getData()->getAuthenticationMethod()->getUsername() -- server-generated
// $trunkDocument->getData()->getAuthenticationMethod()->getPassword() -- server-generatedcodecs lists the codecs offered on calls from the trunk by name, in priority order: the first has the highest priority. The names are the Didww\Enum\VoiceOutCodec cases, which differ from those of an inbound SIP trunk (Codec); getCodecs() returns the raw string for a name this SDK does not know. Left out, the trunk offers pcma, pcmu and telephone_event. ice_mode, rtcp_mux_mode and rtcp_feedback_mode take disabled, accept (the default) or initiate (setIceMode(), setRtcpMuxMode() and setRtcpFeedbackMode()).
An SMS trunk delivers inbound messages, accepts outbound ones, or both. Its configuration is one of five classes in Didww\Item\SmsTrunkConfiguration:
| Type | Class | Notes |
|---|---|---|
sms_to_email |
SmsToEmail |
Inbound messages are forwarded as email. send_to, subject and message are required. |
http_in |
HttpIn |
Inbound messages are sent as an HTTP request to your url. http_method is a Didww\Enum\SmsHttpMethod; post and put also need body_type (a Didww\Enum\SmsBodyType) and body, which get refuses. Query parameters, headers and body may use the placeholders {SMS_TEXT}, {SMS_TEXT_BASE64_ENCODED}, {SMS_SRC_ADDR}, {SMS_DST_ADDR} and {SMS_TIME}. |
http_out |
HttpOut |
You submit outbound messages over HTTP. auth_name and auth_password are generated. The submit URL is $trunk->getHost(). |
smpp_esme |
SmppEsme |
You bind to DIDWW as an SMPP ESME. server_location is required; system_id and password are generated. |
smpp_smsc |
SmppSmsc |
DIDWW binds to your SMSC with your host, system_id, password and server_location. |
The read-only getAllowIn() and getAllowOut() tell which directions a trunk handles. server_location is a Didww\Enum\SmsServerLocation (NYC, AMS); the sandbox accepts nyc only. A configuration type this SDK does not know is read as SmsTrunkConfiguration\Generic and sent back unchanged. Its getAttribute() and the getAttributes() of every configuration return copies: change a value with setAttribute() or a setter, since a value changed in place is not sent.
use Didww\Enum\SmsBodyType;
use Didww\Enum\SmsHttpMethod;
use Didww\Item\SmsTrunkConfiguration\HttpIn;
$configuration = new HttpIn();
$configuration->setUrl('https://example.com/sms');
$configuration->setHttpMethod(SmsHttpMethod::POST);
$configuration->setBodyType(SmsBodyType::JSON);
$configuration->setBody('{"text":"{SMS_TEXT}","from":"{SMS_SRC_ADDR}","to":"{SMS_DST_ADDR}"}');
$trunk = new Didww\Item\SmsTrunk();
$trunk->setName('Inbound webhook');
$trunk->setConfiguration($configuration);
$trunk = $trunk->save()->getData();
// On update the configuration type must stay the same; attributes left out keep their values.
// A setter given null sends an explicit null, e.g. when switching to GET:
$update = new HttpIn();
$update->setHttpMethod(SmsHttpMethod::GET);
$update->setBodyType(null);
$update->setBody(null);
$trunk->setConfiguration($update);
$trunk = $trunk->save()->getData();
// List by configuration type, with the group
$trunks = Didww\Item\SmsTrunk::all([
'filter' => ['configuration.type' => 'http_in,sms_to_email'],
'include' => 'sms_trunk_group',
])->getData();setPriority() sets the routing priority within an SMS trunk group (0-32767, the higher value first, 100 by default; it must stay null on http_out trunks). setOutgoingDids() replaces the whole list of DIDs a trunk may send from, and setAllowAnyDidAsSource(true) allows any DID of the account instead.
The generated credentials of http_out and smpp_esme trunks are read-only and are never sent back on update. var_dump() and print_r() mask them, the password of an smpp_smsc configuration, and the headers of an http_in configuration, which may carry the credentials of your endpoint. A Generic configuration masks every value, since its attributes are not known; only the attribute names and explicit nulls are shown. The getters return the real values. To rotate the generated credentials:
$trunk = Didww\Item\SmsTrunk::build('sms-trunk-uuid');
$trunk->regenerateCredentials(); // POST /sms_trunk_regenerate_credentials
$trunk = Didww\Item\SmsTrunk::find('sms-trunk-uuid')->getData();
$configuration = $trunk->getConfiguration();
if ($configuration instanceof Didww\Item\SmsTrunkConfiguration\HttpOut) {
// $configuration->getAuthName() and $configuration->getAuthPassword() are the new credentials
} elseif ($configuration instanceof Didww\Item\SmsTrunkConfiguration\SmppEsme) {
// $configuration->getSystemId() and $configuration->getPassword() are the new credentials
}An SMS trunk group spreads a DID's inbound messages over its trunks by their priority (the higher value first). http_out trunks cannot join a group. Deleting a group also deletes the trunks in it.
use Swis\JsonApi\Client\Collection;
$group = new Didww\Item\SmsTrunkGroup();
$group->setName('Inbound SMS');
$group->setSmsTrunks(new Collection([Didww\Item\SmsTrunk::build('sms-trunk-uuid')]));
$group = $group->save()->getData();
echo $group->getSmsTrunksCount(); // 1setSmsTrunks() replaces the whole membership of the group: list every trunk to keep. An empty Collection removes them all. A trunk can also join or leave a group with SmsTrunk::setSmsTrunkGroup() (null to leave).
A Sender ID verification covers the sender IDs your outbound messages use. It is created and reviewed outside the API: the API lists and reads verifications, and changes only their name and the SMS trunk their messages are routed through. A closed verification cannot be changed. getStatus() returns a Didww\Enum\SenderIdVerificationStatus and getSenderType() a Didww\Enum\SenderType; isActive(), isClosed() and the other predicates test the status (isStatusNew() for status new). The meta carries setup_price and monthly_price as decimal strings.
use Didww\Enum\SenderIdVerificationStatus;
$verifications = Didww\Item\SenderIdVerification::all([
'filter' => ['status' => SenderIdVerificationStatus::ACTIVE->value],
'include' => 'sms_trunk',
])->getData();
echo $verifications[0]->getMeta()['monthly_price'];
// http_out, smpp_esme or smpp_smsc trunks only. Build it with its id: save() without an id would create, which the API does not support.
$verification = Didww\Item\SenderIdVerification::build('verification-uuid');
$verification->setSmsTrunk(Didww\Item\SmsTrunk::build('sms-trunk-uuid'));
$verification->save();
// Outbound messages stop until a trunk is assigned again
$verification = Didww\Item\SenderIdVerification::build('verification-uuid');
$verification->setSmsTrunk(null);
$verification->save();Deleting an SMS trunk leaves the verifications routed through it without a trunk.
use Didww\Enum\CallbackMethod;
// Order by SKU
$order = new Didww\Item\Order([
'allow_back_ordering' => true,
'items' => [
new Didww\Item\OrderItem\Did(['sku_id' => 'sku-uuid', 'qty' => 2]),
],
]);
$order->setCallbackUrl('https://example.com/callback');
$order->setCallbackMethod(CallbackMethod::POST);
$orderDocument = $order->save();
// Order available DID
$order = new Didww\Item\Order([
'items' => [
new Didww\Item\OrderItem\AvailableDid([
'sku_id' => 'sku-uuid',
'available_did_id' => 'available-did-uuid',
]),
],
]);
// Order reserved DID
$order = new Didww\Item\Order([
'items' => [
new Didww\Item\OrderItem\ReservationDid([
'sku_id' => 'sku-uuid',
'did_reservation_id' => 'reservation-uuid',
]),
],
]);
// Order capacity
$order = new Didww\Item\Order([
'items' => [
new Didww\Item\OrderItem\Capacity([
'capacity_pool_id' => 'pool-uuid',
'qty' => 1,
]),
],
]);$reservation = new Didww\Item\DidReservation();
$reservation->setDescription('Reserved for client');
$reservation->setAvailableDid(Didww\Item\AvailableDid::build('available-did-uuid'));
$reservationDocument = $reservation->save();
$reservationDocument->getData()->getExpiresAt(); // \DateTime
// The reservations that expire first
$reservations = Didww\Item\DidReservation::all(['sort' => 'expires_at'])->getData();
// Delete reservation
$reservationDocument->getData()->delete();$group = new Didww\Item\SharedCapacityGroup();
$group->setName('Shared Group');
$group->setSharedChannelsCount(20);
$group->setCapacityPool(Didww\Item\CapacityPool::build('pool-uuid'));
$groupDocument = $group->save();use Didww\Enum\IdentityType;
$identity = new Didww\Item\Identity([
'first_name' => 'John',
'last_name' => 'Doe',
'phone_number' => '12125551234',
'identity_type' => IdentityType::BUSINESS,
'company_name' => 'Example Ltd',
]);
$identity->setCompanyWebsite('https://example.com'); // business identities only; null clears it
$identity->setCountry(Didww\Item\Country::build('country-uuid'));
$identityDocument = $identity->save();$address = new Didww\Item\Address();
$address->setCityName('New York');
$address->setPostalCode('10001');
$address->setAddress('123 Main St');
$address->setIdentity(Didww\Item\Identity::build('identity-uuid'));
$address->setCountry(Didww\Item\Country::build('country-uuid'));
$addressDocument = $address->save();use Didww\Enum\ExportServiceType;
use Didww\Enum\ExportType;
// CDR export
$export = new Didww\Item\Export();
$export->setExportType(ExportType::CDR_IN);
$export->setFilterFrom('2026-10-01 00:00:00'); // inclusive, UTC
$export->setFilterTo('2026-10-02 00:00:00'); // exclusive, UTC
$export->save();
// SMS export
$export = new Didww\Item\Export();
$export->setExportType(ExportType::SMS_OUT);
$export->setFilterFrom('2026-10-01 00:00:00');
$export->setFilterTo('2026-10-02 00:00:00');
$export->setFilterServiceType(ExportServiceType::A2P);
$export->setFilterSmsTrunkId(['sms-trunk-uuid']); // sent as "sms_trunk.id"
$export = $export->save()->getData();
// The export is pending until its file is generated; read it again later
$export = Didww\Item\Export::find($export->getId())->getData();
if ($export->isCompleted()) {
$result = $export->download('/var/data/sms_out.csv.gz'); // gzipped CSV, as served
if (true !== $result) {
echo "Download failed: $result\n";
}
$export->downloadAndDecompress('/var/data/sms_out.csv'); // plain CSV
}from and to (YYYY-MM-DD HH:MM:SS in UTC) are required for every export type (cdr_in, cdr_out, sms_in, sms_out). The other filters depend on the type, each with its own setter:
cdr_in:setFilterDidNumber(),setFilterSourceNumber(),setFilterSourceNumberOut(),setFilterSourceCountryIso();cdr_out:setFilterVoiceOutTrunkId()(voice_out_trunk.id),setFilterSource(),setFilterCli(),setFilterDestination();sms_inandsms_out:setFilterSourceAddressEq(),setFilterSourceAddressCont(),setFilterDestinationAddressEq(),setFilterDestinationAddressCont(),setFilterStatus(),setFilterSmsId(),setFilterSmsTrunkId()(sms_trunk.id, one id or an array of ids);sms_inonly:setFilterTrunkType(), one or moreDidww\Enum\ExportTrunkTypevalues;sms_outonly:setFilterServiceType(), aDidww\Enum\ExportServiceTypevalue, andsetFilterSenderIdVerificationId()(sender_id_verification.id, one id or an array of ids).
Filter values are lowercase: service_type is a2p or p2p, trunk_type is one or more of smpp_smsc, smpp_esme, sms_to_email and http_in, and status is success, failed or queued for sms_in, and routing_error, in_progress, queued, failed or success for sms_out.
setFilter($key, $value) sets any other key.
download() and downloadAndDecompress() take a file path or a writable stream and return true, or an error message string when the download failed (an HTTP status other than 200, a transport or a file error). download() replaces a path only when the download succeeds. Because the bearer token is sent with it, the export URL must be on the origin (scheme, host and port) of the JSON:API base URL or of the environment's API URL, which the API builds export URLs on even when baseUrl: points elsewhere; any other URL throws an \InvalidArgumentException and nothing is sent. Redirects are not followed, and the body of an error answer is read for the message up to 1 MiB within 60 s. A download to a path is written through a temporary file .didww-<16 hex digits>.tmp in the directory of the path. Both take an optional second argument, set to the Retry-After seconds of an answer other than 200 (null when there is none), as in $export->download($path, $retryAfter); see Error Handling. A token that cannot be obtained throws a DidwwAuthException.
// List address verifications
$verifications = Didww\Item\AddressVerification::all()->getData();
// Create address verification
$verification = new Didww\Item\AddressVerification();
$verification->setCallbackUrl('https://example.com/callback');
$verification->setCallbackMethod(Didww\Enum\CallbackMethod::POST);
$verification->setAddress(Didww\Item\Address::build('address-uuid'));
$verification->setDids(new Swis\JsonApi\Client\Collection([Didww\Item\Did::build('did-uuid')]));
$verificationDocument = $verification->save();// List emergency requirements
$emergReqs = Didww\Item\EmergencyRequirement::all()->getData();
// Create emergency verification
$emergVerification = new Didww\Item\EmergencyVerification();
$emergVerification->setCallbackUrl('https://example.com/callback');
$emergVerification->setCallbackMethod(Didww\Enum\CallbackMethod::POST->value); // takes a string
$emergVerification->setAddress(Didww\Item\Address::build('address-uuid'));
$emergVerification->setDids(new Swis\JsonApi\Client\Collection([Didww\Item\Did::build('did-uuid')]));
$emergVerificationDocument = $emergVerification->save();
// List emergency calling services
$emergServices = Didww\Item\EmergencyCallingService::all()->getData();// List DID history
$history = Didww\Item\DidHistory::all()->getData();
foreach ($history as $entry) {
echo $entry->getAction() . ' ' . $entry->getCreatedAt()->format('Y-m-d') . "\n";
}Prices are served by three services outside the JSON:API (hosts in Environments). Each price list has a price file and a lookup:
| Accessor | Service | Price file | Lookup | Lookup rows |
|---|---|---|---|---|
Didww\Prices::voiceIn() |
Voice IN | prices.csv.gz |
lookup/prices |
Didww\Prices\VoiceInPrice |
Didww\Prices::voiceOut() |
Voice OUT | prices.csv.gz |
lookup/prices |
Didww\Prices\VoiceOutPrice |
Didww\Prices::smsOutA2p() |
SMS | sms_out/a2p/prices.csv.gz |
sms_out/a2p/lookup/prices |
Didww\Prices\SmsOutPrice |
Didww\Prices::smsOutP2p() |
SMS | sms_out/p2p/prices.csv.gz |
sms_out/p2p/lookup/prices |
Didww\Prices\SmsOutPrice |
Didww\Prices::smsOutOtp() |
SMS | sms_out/otp/prices.csv.gz |
sms_out/otp/lookup/prices |
Didww\Prices\SmsOutPrice |
Didww\Prices::smsIn() |
SMS | sms_in/prices.csv.gz |
sms_in/lookup/prices |
Didww\Prices\SmsInPrice |
Each accessor returns a Didww\Prices\PricesService, which uses the configuration current at the time of a call, so call Configuration::configure() first. The account needs a price plan of that service: without one, every call throws a DidwwPricesException of kind PricesErrorKind::PRICE_PLAN_NOT_ASSIGNED.
$result = Didww\Prices::voiceIn()->lookup(['number' => '18005550123', 'src_country_iso' => 'US']);
echo $result->getTotalRecords();
foreach ($result as $price) {
if (null !== $price->getRate()) {
printf("%s %s: %s USD/min\n", $price->getDestination(), $price->getSourceType(), $price->getRate());
}
}
$voiceOut = Didww\Prices::voiceOut()->lookup(['number' => '493012345678']);
$voiceOut->getRows()[0]->getCategory(); // Didww\Prices\VoiceOutPriceCategory
$a2p = Didww\Prices::smsOutA2p()->lookup(['dst_number' => '4915123456789']);
$smsIn = Didww\Prices::smsIn()->lookup(['dst_country_iso' => 'US']);| Service | Filters |
|---|---|
| Voice IN | number (required), src_country_iso |
| Voice OUT | number (required); no other filter |
| SMS OUT and SMS IN | dst_number, dst_country_iso; at least one |
A missing or unknown filter throws an \InvalidArgumentException before any request; null and blank values are dropped. The server checks the value formats and answers a bad value with 400 (PricesErrorKind::BAD_REQUEST).
lookup() returns a Didww\Prices\PriceLookup: iterate it, count() it, or call getRows() and getTotalRecords(). It always holds at least one row: no match throws PricesErrorKind::PRICE_NOT_FOUND, never an empty result. The rows are read-only objects with typed getters. Prices and fees are ?float in USD, like the other decimal values of the SDK; they are null when the row rejects the destination (getRejectCalls() or getRejectSms()), and SmsInPrice::getPrice() is a float. Intervals and increments are int (?int for the scheduled getNext*Increment() values), SmsOutPrice::getMcc() and getMnc() are ?int, VoiceOutPrice::getEffectiveAt() is a ?\DateTimeImmutable and VoiceOutPrice::getCategory() is a Didww\Prices\VoiceOutPriceCategory (or the raw string for a value this SDK does not know).
The id of an SMS OUT or SMS IN lookup row is derived from its content: it changes when the row or its price changes, so do not use it to track a destination over time. A Voice OUT id stays the same when a re-import changes only the price. A Voice IN id names the answering row of the plan.
The files are gzipped CSV with a header row. The SDK writes them exactly as served and never decompresses them.
use Didww\Prices\PriceFileReader;
$prices = Didww\Prices::voiceOut();
// Download unless the copy at the path is current
$file = $prices->fetch('/var/data/voice_out_prices.csv.gz');
if ($file->isNotModified()) {
echo "answered 304, the file was kept\n";
} else {
printf("downloaded %d bytes, last modified %s\n", $file->getBytesWritten(), $file->getLastModified()?->format(DATE_ATOM));
}
// Read the rows
foreach (PriceFileReader::rows('/var/data/voice_out_prices.csv.gz') as $row) {
echo $row['Prefix'] . ': ' . $row['Rate'] . "\n";
}
// Lower-level calls
$status = $prices->head($file->getLastModified()); // sent as If-Modified-Since; null sends none
// $status->isNotModified(), $status->getContentLength() (null when unknown),
// $status->getFilename() (from Content-Disposition, e.g. "voice_out_prices.csv.gz")
$prices->download('/var/data/voice_out_prices.csv.gz');
$stream = fopen('php://temp', 'w+b');
$prices->download($stream); // any writable stream resource or Psr\Http\Message\StreamInterfacefetch($path)sends the modification time of the file at$pathasIf-Modified-Since, when the file is there; an unchanged price file is answered 304 and the file is kept. A file written bydownload($path)orfetch()gets theLast-Modifiedof the response as its modification time, so the date matches the copy on disk. On a stream wrapper that cannot set modification times (nostream_metadata()), the file keeps the time it was written, so usedownload($path, $file->getLastModified())with the date you kept instead offetch()there.fetch()trusts the modification time of any file at$path: a file copied or changed by other means can be answered 304 and kept, so replace such a file withdownload($path).download($path)andfetch()write the body into a temporary file.didww-<16 hex digits>.tmpin the directory of$path, unique to the call, which gets the mode of a new file (0666minus the umask) and replaces$pathatomically only on a 200. A 304 or an error leaves an existing file untouched, the temporary file is always removed, and concurrent downloads to one path do not mix their bytes.download($stream, $ifModifiedSince = null)writes the body into the stream only on a 200, as it arrives, so after a transfer error the stream may hold part of it. An exception thrown by the stream propagates as is.head(),download()andfetch()return aDidww\Prices\PriceFile:getStatusCode(),getLastModified()(nullwhen absent),getContentLength(),getFilename(),getBytesWritten()andisNotModified().PriceFileReader::rows($pathOrStream)gunzips a downloaded file and yields each row as an array keyed by the header line as is. Prices are in USD with VAT excluded. Voice IN:Country,Src country name,Source type,Destination,Rate,Connection fee,Initial interval,Next intervalandReject calls. Voice OUT:Category,Country,Network,Prefix(one prefix per row),Rate,Connection fee,Initial increment,Recurring increment,Reject calls,Next rate,Next connection fee,Next initial increment,Next recurring increment,Effective dateandComment. SMS OUT:Source prefix,Destination prefix,Country,MCC,MCC name,MNC,MNC name,Reject SMS(trueorfalse) andPrice. SMS IN:Source prefix,Source number length min,Source number length max,Destination prefix,Destination number length min,Destination number length max,CountryandPrice. The rows are read lazily. Input that is not gzip, a file cut short and a row whose field count differs from the header throw an\UnexpectedValueException, after the rows before it have been yielded. A path that cannot be opened throws a\RuntimeExceptionwhen the rows are first read.- Only
Last-ModifiedandIf-Modified-Sinceare used. The service sends noETag, and the SDK never sendsIf-None-Match, which would make the service ignoreIf-Modified-Since. - A 503 on a price file is retried up to 2 times when its
Retry-Afteris 60 seconds or less, after waiting that long (at least 1 s) plus a small random delay so that clients do not retry in step. Otherwise it throwsPricesErrorKind::SERVICE_UNAVAILABLEwithgetRetryAfter(). Lookups are not retried. The wait blocks the process: run price file downloads from the command line or a scheduled job (cron), not within a web request. - A 404
price_not_foundthrowsPricesErrorKind::PRICE_NOT_FOUND; any other 404,price_plan_not_assignedincluded, and any 404 onhead(), which has no body, throwsPricesErrorKind::PRICE_PLAN_NOT_ASSIGNED.getErrorCode()holds the code of the answer, orprice_plan_not_assignedfor a 404 without one. - Redirects are not followed. A status without its own kind in Error Handling, such as a 3xx, a 202 or a 204, throws
PricesErrorKind::UNEXPECTED_STATUS. An error is never turned into an empty file or an empty result.
$regionsDocument = Didww\Item\Region::all([
'filter' => ['country.id' => 'uuid', 'name' => 'Arizona'],
'include' => 'country',
'sort' => 'name',
'page' => ['size' => 25, 'number' => 1],
]);
$regions = $regionsDocument->getData();See
FILTERS.mdfor the list offilter[KEY]keys accepted by every list endpoint at API version2026-11-19.
The JSON:API resources return every answer, errors included, as a document with an error collection. Check hasErrors() after every call.
// Validation errors (422) — e.g. creating a resource with invalid data
$document = $order->save();
if ($document->hasErrors()) {
foreach ($document->getErrors() as $error) {
echo $error->getDetail() . "\n";
// e.g. "name - has already been taken"
}
}
// Not found (404)
$document = Didww\Item\Did::find('non-existent-uuid');
if ($document->hasErrors()) {
foreach ($document->getErrors() as $error) {
echo $error->getTitle() . ': ' . $error->getDetail() . "\n";
// "Record not found: The record identified by non-existent-uuid could not be found."
}
}The authentication failures of the API arrive the same way: a 401 still answered after the token was replaced once, and a 403 such as insufficient_scope for a write with a read token, which is never retried, are document errors with getStatus() "401" or "403". EncryptedFile::upload() reports any error status in its UploadResult (success(), getResponseCode(), getErrors()), and a transport failure as response code 0. Export::download() returns an error message for any status other than 200. A transport failure of a JSON:API call throws the Guzzle exception (GuzzleHttp\Exception\TransferException) as before.
A 429 (too_many_requests) means the request budget of the account for the current window is spent. It arrives the same way: as a document error with getStatus() "429", in the UploadResult of EncryptedFile::upload(), or as the error message of Export::download() and downloadAndDecompress(). The SDK does not retry it, as a write may not be safe to send twice: wait the Retry-After seconds before sending the request again. Didww\RetryAfter::seconds($document) reads them from the document of a JSON:API call, UploadResult::getRetryAfter() from an upload, and the optional second argument of the export downloads is set to them. Each is the Retry-After of an error answer, whatever its status, and null when it is missing or not a number of seconds.
use Didww\RetryAfter;
$document = $trunk->save();
if ($document->hasErrors() && '429' === $document->getErrors()->first()->getStatus()) {
echo 'API rate limit, retry after ' . RetryAfter::seconds($document) . " s\n";
}
$result = $export->download('/var/data/export.csv.gz', $retryAfter);
if (true !== $result && null !== $retryAfter) {
echo "$result, retry after $retryAfter s\n";
}The token service and the prices services throw exceptions instead, which carry a kind:
use Didww\Exception\AuthErrorKind;
use Didww\Exception\DidwwAuthException;
use Didww\Exception\DidwwExceptionInterface;
use Didww\Exception\DidwwPricesException;
use Didww\Exception\PricesErrorKind;
try {
$result = Didww\Prices::smsOutA2p()->lookup(['dst_number' => '4915123456789']);
} catch (DidwwAuthException $e) {
if (AuthErrorKind::RATE_LIMITED === $e->getKind()) {
// Wait getRetryAfter() seconds and try again; repeat while the kind is RATE_LIMITED.
echo 'Token service rate limit, retry after ' . $e->getRetryAfter() . "\n";
} elseif (AuthErrorKind::INVALID_CLIENT === $e->getKind()) {
echo 'API key refused: ' . $e->getMessage() . "\n";
} else {
echo 'No access token: ' . $e->getMessage() . "\n";
}
} catch (DidwwPricesException $e) {
match ($e->getKind()) {
PricesErrorKind::PRICE_NOT_FOUND => print("No price for this number\n"),
PricesErrorKind::TOO_MANY_REQUESTS => print('Prices rate limit, retry after ' . $e->getRetryAfter() . "\n"),
default => print('Prices error: ' . $e->getMessage() . "\n"),
};
}
// Or catch the token service and prices exceptions together
try {
$result = Didww\Prices::voiceIn()->lookup(['number' => '18005550123']);
} catch (DidwwExceptionInterface $e) {
echo $e->getMessage() . "\n";
}Only DidwwAuthException and DidwwPricesException implement Didww\Exception\DidwwExceptionInterface. Their messages never contain the API key or a token. The interface does not cover the other exceptions the SDK can throw: the Guzzle exception (GuzzleHttp\Exception\TransferException) for a transport failure of a JSON:API call, \InvalidArgumentException for invalid arguments, filters or configuration, and the \RuntimeException and \UnexpectedValueException of the prices services and PriceFileReader described below and in Price files.
Token service (DidwwAuthException, with getKind(), getStatusCode(), getError(), getErrorDescription() and getRetryAfter()). It is thrown from any call that needs a new token, JSON:API calls included:
AuthErrorKind |
Thrown when |
|---|---|
INVALID_CLIENT |
401: the token service refused the API key. Not retried. |
INVALID_REQUEST |
400, e.g. invalid_request or invalid_scope. |
RATE_LIMITED |
429. getRetryAfter() is the server's wait. Further token requests fail without a request until that time plus a small random delay has passed; such a refusal reports the time still left in getRetryAfter(), so retry in a loop rather than once. |
SERVER_ERROR |
5xx on the last of the 4 attempts. |
CONNECTION_ERROR |
Connection failure or timeout on the last attempt, a TLS failure, or the token request could not be sent, for example because of an invalid HTTP client option (the last two are not retried). |
INVALID_GRANT |
The token is empty or does not cover the requested audience. |
UNEXPECTED_STATUS |
Any other status, such as a redirect. |
Prices (DidwwPricesException, with getKind(), getStatusCode(), getErrorCode(), getErrors() and getRetryAfter()):
PricesErrorKind |
Status |
|---|---|
BAD_REQUEST |
400, e.g. a filter value of the wrong format |
NOT_AUTHORIZED |
401 after the token was replaced once |
ACCESS_DENIED |
403 |
PRICE_PLAN_NOT_ASSIGNED |
404 price_plan_not_assigned, and any other 404 except price_not_found, including any 404 on head(), which has no body |
PRICE_NOT_FOUND |
404 price_not_found: no price matches the lookup |
NOT_ACCEPTABLE |
406 |
TOO_MANY_REQUESTS |
429, with getRetryAfter(). Not retried. |
SERVICE_UNAVAILABLE |
503, with getRetryAfter(). Retried on price files only, see Price files. |
UNEXPECTED_STATUS |
Any other status |
CONNECTION_ERROR |
Connection failure, timeout, TLS failure or a response body that breaks off. Not retried. An exception writing the destination stream propagates as is. |
The prices services can also throw a DidwwAuthException, lookup() an \InvalidArgumentException for invalid filters and an \UnexpectedValueException when a 200 answer is not a JSON:API document it can parse or holds no prices, and download() and fetch() a \RuntimeException for the file errors of the path (temporary file, times, rename).
| Resource | Class | Operations |
|---|---|---|
| Country | Didww\Item\Country |
list, find |
| Region | Didww\Item\Region |
list, find |
| City | Didww\Item\City |
list, find |
| Area | Didww\Item\Area |
list, find |
| NanpaPrefix | Didww\Item\NanpaPrefix |
list, find |
| DidGroup | Didww\Item\DidGroup |
list, find |
| AvailableDid | Didww\Item\AvailableDid |
list, find |
| ProofType | Didww\Item\ProofType |
list, find |
| PublicKey | Didww\Item\PublicKey |
list, find |
| AddressRequirement | Didww\Item\AddressRequirement |
list, find |
| SupportingDocumentTemplate | Didww\Item\SupportingDocumentTemplate |
list, find |
| Balance | Didww\Item\Balance |
find |
| Did | Didww\Item\Did |
list, find, update |
| VoiceInTrunk | Didww\Item\VoiceInTrunk |
list, find, create, update, delete |
| VoiceInTrunkGroup | Didww\Item\VoiceInTrunkGroup |
list, find, create, update, delete |
| VoiceOutTrunk | Didww\Item\VoiceOutTrunk |
list, find, create, update, delete |
| VoiceOutTrunkRegenerateCredential | Didww\Item\VoiceOutTrunkRegenerateCredential |
create |
| SmsTrunk | Didww\Item\SmsTrunk |
list, find, create, update, delete |
| SmsTrunkGroup | Didww\Item\SmsTrunkGroup |
list, find, create, update, delete |
| SmsTrunkRegenerateCredential | Didww\Item\SmsTrunkRegenerateCredential |
create |
| SenderIdVerification | Didww\Item\SenderIdVerification |
list, find, update |
| DidReservation | Didww\Item\DidReservation |
list, find, create, delete |
| CapacityPool | Didww\Item\CapacityPool |
list, find, update |
| SharedCapacityGroup | Didww\Item\SharedCapacityGroup |
list, find, create, update, delete |
| Order | Didww\Item\Order |
list, find, create, delete |
| Export | Didww\Item\Export |
list, find, create, update |
| Address | Didww\Item\Address |
list, find, create, update, delete |
| AddressVerification | Didww\Item\AddressVerification |
list, find, create, update |
| Identity | Didww\Item\Identity |
list, find, create, update, delete |
| EncryptedFile | Didww\Item\EncryptedFile |
list, find, delete, upload |
| PermanentSupportingDocument | Didww\Item\PermanentSupportingDocument |
create, delete |
| Proof | Didww\Item\Proof |
create, delete |
| AddressRequirementValidation | Didww\Item\AddressRequirementValidation |
create |
| DidHistory | Didww\Item\DidHistory |
list |
| EmergencyRequirement | Didww\Item\EmergencyRequirement |
list, find |
| EmergencyRequirementValidation | Didww\Item\EmergencyRequirementValidation |
create |
| EmergencyCallingService | Didww\Item\EmergencyCallingService |
list, find, delete |
| EmergencyVerification | Didww\Item\EmergencyVerification |
list, find, create, update |
| VoiceInPrice | Didww\Prices::voiceIn() |
lookup, head, download, fetch |
| VoiceOutPrice | Didww\Prices::voiceOut() |
lookup, head, download, fetch |
| SmsOutPrice | Didww\Prices::smsOutA2p(), smsOutP2p(), smsOutOtp() |
lookup, head, download, fetch |
| SmsInPrice | Didww\Prices::smsIn() |
lookup, head, download, fetch |
The price rows are served by the prices services outside the JSON:API, see Prices.
Date and datetime attributes returned from the API are represented as strings in the underlying JSON. This SDK provides typed getter methods for some known date and datetime attributes; these getters convert those string values to \DateTime instances.
- Datetime getters — return
\DateTimewith full timestamp:getCreatedAt()— present on most resourcesgetUpdatedAt()—SmsTrunk,SmsTrunkGroupgetExpiresAt()—Did,DidReservation,Proof,EncryptedFile(nullable)getActivatedAt()—EmergencyCallingService,SenderIdVerification(nullable)getCanceledAt()—EmergencyCallingService(nullable)getClosedAt()—SenderIdVerification(nullable)
- Date-only getters — return
\DateTimewith time00:00:00in the default time zone of PHP:Identity::getBirthDate()EmergencyCallingService::getRenewDate()(nullable)
- Getters that return date-only strings —
"YYYY-MM-DD":CapacityPool::getRenewDate()(nullable)SenderIdVerification::getRenewDate()— nullable,nullonce the verification is closed- Order item
getBilledFrom()/getBilledTo()
- Prices —
\DateTimeImmutable:VoiceOutPrice::getEffectiveAt()(nullable)PriceFile::getLastModified()(nullable, UTC)
- String fields (not numeric):
EmergencyRequirement::getEstimateSetupTime()— e.g."7-14 days","1"EmergencyRequirement::getRequirementRestrictionMessage()— nullable
Important changes from previous API versions:
getExpireAt()renamed togetExpiresAt()onDidReservationandEncryptedFileCapacityPool::getRenewDate()returns a date-only string, NOT a\DateTimegetEstimateSetupTime()returns a string, NOT an integer
$did = Didww\Item\Did::find('uuid')->getData();
echo $did->getCreatedAt()->format('Y-m-d H:i:s'); // e.g. "2024-01-15 10:00:00"
echo $did->getExpiresAt()?->format('Y-m-d'); // null or "2025-01-15"
$identity = Didww\Item\Identity::find('uuid')->getData();
echo $identity->getBirthDate()->format('Y-m-d'); // e.g. "1990-05-20"The SDK provides PHP 8.2+ backed enum classes for all API option fields (for example CallbackMethod, IdentityType, OrderStatus, ExportType, CliFormat, OnCliMismatchAction, MediaEncryptionMode, TransportProtocol, Codec, VoiceOutCodec, IceMode, and more).
use Didww\Enum\CallbackMethod;
use Didww\Enum\IdentityType;
$order = new Didww\Item\Order();
$order->setCallbackMethod(CallbackMethod::POST);
$identity = new Didww\Item\Identity();
$identity->setIdentityType(IdentityType::BUSINESS);All setters accept both enum constants and raw string/integer values for backward compatibility:
use Didww\Enum\OnCliMismatchAction;
// Both are equivalent
$trunk->setOnCliMismatchAction(OnCliMismatchAction::REPLACE_CLI);
$trunk->setOnCliMismatchAction('replace_cli');Getters of the newer attributes (getNumberType(), getPop(), getCodecs(), getIceMode(), getRtcpMuxMode(), getRtcpFeedbackMode(), the SMS trunk configuration and Sender ID verification getters, VoiceOutPrice::getCategory()) return the enum, or the raw string for a value this SDK version does not know yet.
Namespace Didww\Enum, unless noted:
| Enum | Backing Type | Values |
|---|---|---|
CliFormat |
string |
RAW, E164, LOCAL |
IdentityType |
string |
PERSONAL, BUSINESS |
OrderStatus |
string |
PENDING, CANCELED, COMPLETED |
CallbackMethod |
string |
POST, GET |
ExportType |
string |
CDR_IN, CDR_OUT, SMS_IN, SMS_OUT |
ExportStatus |
string |
PENDING, PROCESSING, COMPLETED |
ExportTrunkType |
string |
SMPP_SMSC, SMPP_ESME, SMS_TO_EMAIL, HTTP_IN (trunk_type filter of sms_in exports) |
ExportServiceType |
string |
A2P, P2P (service_type filter of sms_out exports) |
AddressVerificationStatus |
string |
PENDING, APPROVED, REJECTED |
MediaEncryptionMode |
string |
DISABLED, SRTP_SDES, SRTP_DTLS, ZRTP |
StirShakenMode |
string |
DISABLED, ORIGINAL, PAI, ORIGINAL_PAI, VERSTAT |
OnCliMismatchAction |
string |
SEND_ORIGINAL_CLI, REJECT_CALL, REPLACE_CLI*, RANDOMIZE_CLI* |
DefaultDstAction |
string |
ALLOW_ALL, REJECT_ALL |
VoiceOutTrunkStatus |
string |
ACTIVE, BLOCKED |
Feature |
string |
VOICE_IN, VOICE_OUT, T38, SMS_IN, P2P, A2P, EMERGENCY, CNAM_OUT |
AreaLevel |
string |
WORLDWIDE, COUNTRY, AREA, CITY |
NumberType |
string |
LOCAL, NATIONAL, MOBILE, TOLL_FREE, SHARED_COST, GLOBAL |
Pop |
string |
NYC, FRA, LAC, MIA, SG, HK, AMS (values in lowercase, such as nyc) |
SenderIdVerificationStatus |
string |
ACTIVE, CHANGES_REQUIRED, CLOSED, CLOSING_IN_PROCESS, IN_PROCESS, NEW |
SenderType |
string |
ALPHANUMERIC, CARRIER, LONG_CODE, SHORT_CODE, TOLL_FREE |
SmsHttpMethod |
string |
GET, POST, PUT |
SmsBodyType |
string |
JSON, HTML_MULTIPART, HTML_URL_ENCODED, RAW |
SmsServerLocation |
string |
NYC, AMS |
Codec |
string |
Codecs of an inbound SIP trunk: TELEPHONE_EVENT, G723, G729, PCMU, PCMA, SPEEX, GSM, G726_32, G721, G726_24, G726_40, G726_16, L16, AMR, AMR_WB |
VoiceOutCodec |
string |
Codecs of a Voice OUT trunk: TELEPHONE_EVENT, G723, G729, PCMU, PCMA, GSM, G722, OPUS, AMR, AMR_WB |
IceMode, RtcpMuxMode, RtcpFeedbackMode |
string |
DISABLED, ACCEPT, INITIATE |
TransportProtocol |
int |
UDP(1), TCP(2), TLS(3) |
RxDtmfFormat |
int |
RFC_2833(1), SIP_INFO(2), RFC_2833_OR_SIP_INFO(3) |
TxDtmfFormat |
int |
DISABLED(0), RFC_2833(1), SIP_INFO_RELAY(2), SIP_INFO_DTMF(4) |
SstRefreshMethod |
int |
INVITE(1), UPDATE(2), UPDATE_FALLBACK_INVITE(3) |
EmergencyCallingServiceStatus |
string |
ACTIVE, CANCELED, CHANGES_REQUIRED, IN_PROCESS, NEW, PENDING_UPDATE |
EmergencyVerificationStatus |
string |
PENDING, APPROVED, REJECTED |
DiversionRelayPolicy |
string |
NONE, AS_IS, SIP, TEL |
ReroutingDisconnectCode |
int |
47 SIP error codes (56-108, 1505) |
Didww\Prices\VoiceOutPriceCategory |
string |
INTERNATIONAL, ORIGIN_BASED, LOCAL |
Didww\Auth\Scope |
string |
READ, FULL |
Didww\Exception\AuthErrorKind, Didww\Exception\PricesErrorKind |
string |
See Error Handling |
* REPLACE_CLI and RANDOMIZE_CLI require additional account configuration. Contact DIDWW support to enable these values.
The SDK provides an Encrypt utility for encrypting files before upload, using RSA-OAEP + AES-256-CBC (matching DIDWW's encryption requirements).
$fileContents = file_get_contents('/path/to/document.pdf');
$enc = new Didww\Encrypt();
$fingerprint = $enc->getFingerprint();
$encData = $enc->encrypt($fileContents);
$uploadResult = Didww\Item\EncryptedFile::upload($fingerprint, $encData, 'file description');
if ($uploadResult->success()) {
echo $uploadResult->getId() . "\n";
} elseif (429 === $uploadResult->getResponseCode()) {
echo 'Retry after ' . $uploadResult->getRetryAfter() . " s\n";
}Validate incoming webhook callbacks from DIDWW using HMAC-SHA1 signature verification.
Initialize the validator with the callback secret that is enabled in the DIDWW User Panel (APIs → DIDWW API 3 → Callback Secrets). DIDWW signs every callback with it and sends callbacks only while a callback secret is enabled.
$validator = new Didww\Callback\RequestValidator('YOUR_CALLBACK_SECRET');
$valid = $validator->validate(
$requestUrl, // full original URL
$payloadParams, // array of payload key-value pairs
$signature // value of X-DIDWW-Signature header
);| Type | Class |
|---|---|
| SIP | Didww\Item\Configuration\Sip |
| PSTN | Didww\Item\Configuration\Pstn |
For the SMS trunk configuration types, see SMS Trunks.
| Type | Class |
|---|---|
| DID | Didww\Item\OrderItem\Did |
| Available DID | Didww\Item\OrderItem\AvailableDid |
| Reservation DID | Didww\Item\OrderItem\ReservationDid |
| Capacity | Didww\Item\OrderItem\Capacity |
| Emergency | Didww\Item\OrderItem\Emergency |
| Generic | Didww\Item\OrderItem\Generic |
11.0.0 targets API 2026-11-19 only. To stay on API 2026-04-16, keep 10.x (^10.2, branch release-10).
Most code keeps working: new Credentials($apiKey, $env) and Configuration::configure($credentials, $httpClientConfig) are unchanged, and the SDK mints the access tokens itself. The breaking changes:
- Authentication. Every request carries a bearer token minted from the API key (see Authentication). The
Api-Keyheader is sent only to the token service, so outgoing traffic must reachauth.didww.com(auth-sandbox.didww.comin the sandbox). The token service can throw aDidwwAuthExceptionfrom any call. - API version.
X-DIDWW-API-Versionis no longer sent: the version is requested in the token. The default is2026-11-19, and an earlier version throws an\InvalidArgumentException. Anullversion inCredentialsnow means the default, not "send no version". - Validation.
Credentialsandconfigure()throw an\InvalidArgumentExceptionfor invalid values (see Validation). An environment other thanproductionandsandboxis rejected; 10.x fell back to the sandbox. - Removed methods.
Didww\Client::setApiKey()andClient::setVersion()are removed: authentication and the API version come fromCredentialsandconfigure(). - Codecs. The SIP configuration of a Voice IN trunk takes codec names:
Sip::getCodecs()andsetCodecs()(thecodecsattribute) replacegetCodecIds()andsetCodecIds()(codec_ids), andDidww\Enum\Codecis backed by the names ('pcmu') instead of the ids (9).Configuration\Base::getDefaultCodecIds()andBase::getCodecs()are removed: the server chooses the codecs of a trunk created without them, andCodec::cases()lists the names. - API values.
ProofType::getEntityType()and theentity_typefilter of proof types useaddress,businessandpersonal; the filter refuses another spelling, such asAddress.AddressRequirement::getPersonalMandatoryFields()andgetBusinessMandatoryFields()return an empty array when no field is mandatory; 10.x declared themarraybut returned the attribute as sent, so thenullthat API2026-04-16sends in that case threw aTypeError. The address requirement liststax_idinstead ofvat_id, and the emergency requirement lists API field names, such astax_idandarea, instead of labels (see Read-Only Resources). - Removed resources.
Didww\Item\PopandDidww\Item\DidGroupTypeare removed, with thedid_group_typerelationship.DidGroup,AddressRequirement,EmergencyRequirementandEmergencyCallingServicehavegetNumberType()instead ofdidGroupType(); filter withnumber_typeinstead ofdid_group_type.id.VoiceInTrunk::pop()is removed andsetPop()takes aDidww\Enum\Pop, a string ornull; read it withgetPop(). - HTTP defaults. 10.x used the Guzzle defaults (redirects followed, responses decompressed, no timeouts). 11.x connects within 10 s, aborts a transfer that stalls (under 1 byte/s) for 60 s, follows no redirects and decompresses nothing (see HTTP client). A
timeoutyou pass, such as['timeout' => 20], still works, but it now also bounds price and export file downloads. - Export download and file upload.
Export::download(),Export::downloadAndDecompress()andEncryptedFile::upload()go through the Guzzle client of the SDK with the bearer token. An export downloads only from the API origin (an\InvalidArgumentExceptionotherwise), only a 200 succeeds, and redirects are not followed; thetrue|stringresult is unchanged. - Guzzle 8.
guzzlehttp/guzzle^8.0.1is required (10.x allowed Guzzle 7). Guzzle 8 changes its own API, so update any code of yours that uses Guzzle directly, such as ahandler, middleware or callbacks you pass in$httpClientConfig, following Guzzle's upgrade guide. In particular a transport failure of a JSON:API call now throws Guzzle 8's exception classes: only aGuzzleHttp\Exception\ResponseException(such as a timeout after the response headers,ResponseTimeoutException) hasgetResponse(), aConnectExceptionorNetworkExceptionhas none, andgetHandlerContext()is gone. - Requirements.
ext-zlibandpsr/logare now required.
New in 11.0.0: SMS trunks, SMS trunk groups, Sender ID verifications, DID SMS routing, sms_in and sms_out exports, prices, DidGroup::getIsDemo(), Identity company website, the codecs, ice_mode, rtcp_mux_mode and rtcp_feedback_mode of Voice OUT trunks and of the SIP configuration of Voice IN trunks (Didww\Enum\VoiceOutCodec, IceMode, RtcpMuxMode and RtcpFeedbackMode), Didww\Enum\ExportServiceType, the Retry-After of a 429 (Didww\RetryAfter, UploadResult::getRetryAfter() and the $retryAfter argument of the export downloads, see Error Handling), the scope:, tokenStore:, logger: and URL arguments of configure(), and the token stores (MemoryTokenStore, ApcuTokenStore as the default outside the CLI with APCu enabled, Psr16TokenStore).
composer install
vendor/bin/phpunit
composer check-styleBug reports and pull requests are welcome on GitHub at https://github.com/didww/didww-api-3-php-sdk
The package is available as open source under the terms of the MIT License.