Telnyx PHP API library

The Telnyx PHP library provides convenient access to the Telnyx REST API from any PHP 8.1.0+ application.

It is generated with Stainless.

composer require "telnyx/telnyx-php 7.15.0"

This library uses named parameters to specify optional arguments. Parameters with a default value must be set by name.

<?php

use Telnyx\Client;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

$response = $client->calls->dial(
  connectionID: 'conn12345',
  from: '+15557654321',
  to: '+15551234567',
  webhookURL: 'https://your-webhook.url/events',
);

var_dump($response->data);

It is recommended to use the static with constructor AzureVoiceSettings::with(type: 'azure', ...) and named parameters to initialize value objects.

However, builders are also provided (new AzureVoiceSettings)->withType('azure').

List methods in the Telnyx API are paginated.

This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually:

<?php

use Telnyx\Client;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

$page = $client->accessIPAddress->list(pageNumber: 1, pageSize: 50);

var_dump($page);

// fetch items from the current page
foreach ($page->getItems() as $item) {
  var_dump($item->id);
}
// make additional network requests to fetch items from all pages, including and after the current page
foreach ($page->pagingEachItem() as $item) {
  var_dump($item->id);
}

When the library is unable to connect to the API, or if the API returns a non-success status code (i.e., 4xx or 5xx response), a subclass of Telnyx\Core\Exceptions\APIException will be thrown:

<?php

use Telnyx\Core\Exceptions\APIConnectionException;
use Telnyx\Core\Exceptions\RateLimitException;
use Telnyx\Core\Exceptions\APIStatusException;

try {
  $numberOrder = $client->numberOrders->create();
} catch (APIConnectionException $e) {
  echo "The server could not be reached", PHP_EOL;
  var_dump($e->getPrevious());
} catch (RateLimitException $e) {
  echo "A 429 status code was received; we should back off a bit.", PHP_EOL;
} catch (APIStatusException $e) {
  echo "Another non-200-range status code was received", PHP_EOL;
  echo $e->getMessage();
}

Error codes are as follows:

Cause	Error Type
HTTP 400	BadRequestException
HTTP 401	AuthenticationException
HTTP 403	PermissionDeniedException
HTTP 404	NotFoundException
HTTP 409	ConflictException
HTTP 422	UnprocessableEntityException
HTTP 429	RateLimitException
HTTP >= 500	InternalServerException
Other HTTP error	APIStatusException
Timeout	APITimeoutException
Network error	APIConnectionException

Certain errors will be automatically retried 2 times by default, with a short exponential backoff.

Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, 429 Rate Limit, >=500 Internal errors, and timeouts will all be retried by default.

You can use the maxRetries option to configure or disable this:

<?php

use Telnyx\Client;

// Configure the default for all requests:
$client = new Client(requestOptions: ['maxRetries' => 0]);

// Or, configure per-request:
$result = $client->numberOrders->create(
  phoneNumbers: [['phoneNumber' => '+15558675309']],
  requestOptions: ['maxRetries' => 5],
);

You can send undocumented parameters to any endpoint, and read undocumented response properties, like so:

Note: the extra* parameters of the same name overrides the documented parameters.

<?php

$numberOrder = $client->numberOrders->create(
  phoneNumbers: [['phoneNumber' => '+15558675309']],
  requestOptions: [
    'extraQueryParams' => ['my_query_parameter' => 'value'],
    'extraBodyParams' => ['my_body_parameter' => 'value'],
    'extraHeaders' => ['my-header' => 'value'],
  ],
);

If you want to explicitly send an extra param, you can do so with the extra_query, extra_body, and extra_headers under the request_options: parameter when making a request, as seen in the examples above.

To make requests to undocumented endpoints while retaining the benefit of auth, retries, and so on, you can make requests using client.request, like so:

<?php

$response = $client->request(
  method: "post",
  path: '/undocumented/endpoint',
  query: ['dog' => 'woof'],
  headers: ['useful-header' => 'interesting-value'],
  body: ['hello' => 'world']
);

This package follows SemVer conventions. As the library is in initial development and has a major version of 0, APIs may change at any time.

This package considers improvements to the (non-runtime) PHPDoc type definitions to be non-breaking changes.

PHP 8.1.0 or higher.

See the contributing documentation.

<?php
require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Credentials\CredentialProvider;
use Aws\Exception\AwsException;

$telnyxAPIKey = getenv('TELNYX_API_KEY');
if (!$telnyxAPIKey) {
	die('TELNYX_API_KEY environment variable not set');
}

$region = 'us-central-1';
$endpoint = "https://{$region}.telnyxcloudstorage.com";

// 1. Initializing the AWS client with specific options
$s3Client = new S3Client([
	'region'  => $region,
	'version' => 'latest',
	'endpoint' => $endpoint,
	'credentials' => [
    	'key'	=> $telnyxAPIKey,
    	'secret' => $telnyxAPIKey,
	],
	'use_path_style_endpoint' => true
]);

$bucketName = "test-bucket-" . $region . '-' . date('H-i') . '-' . rand(0, 1000000);
echo "Generated bucket name: " . $bucketName . PHP_EOL;

// 2. Create a bucket
try {
	$s3Client->createBucket([
    	'Bucket' => $bucketName
	]);
	echo "Created bucket: {$bucketName}" . PHP_EOL;
} catch (AwsException $e) {
	die("Unable to create bucket: " . $e->getMessage());
}

// 3. Upload two objects with random data
for ($i = 0; $i < 2; $i++) {
	$content = random_bytes(1024 * 32); // 32KB of random data
	$objName = "{$i}.txt";
	try {
    	$s3Client->putObject([
        	'Bucket' => $bucketName,
        	'Key'	=> $objName,
        	'Body'   => $content
    	]);
    	echo "Uploaded file ({$objName}) to bucket: {$bucketName}" . PHP_EOL;
	} catch (AwsException $e) {
    	die("Unable to upload file ({$objName}): " . $e->getMessage());
	}
}

// 4. List objects in the bucket
try {
	$result = $s3Client->listObjects([
    	'Bucket' => $bucketName
	]);
	foreach ($result['Contents'] as $item) {
    	echo "Listed object: " . $item['Key'] . PHP_EOL;
	}
} catch (AwsException $e) {
	die("Unable to list objects: " . $e->getMessage());
}

// 5. Download the first object
try {
	$result = $s3Client->getObject([
    	'Bucket' => $bucketName,
    	'Key'	=> '1.txt'
	]);
	$data = $result['Body']->getContents();
	echo "Downloaded file size: " . strlen($data) . PHP_EOL;
} catch (AwsException $e) {
	die("Unable to download object: " . $e->getMessage());
}

// 6. Create a presigned URL for the first file
$url = "https://api.telnyx.com/v2/storage/buckets/{$bucketName}/1.txt/presigned_url";

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['TTL' => 30]));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
	'Authorization: Bearer ' . $telnyxAPIKey,
	'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$httpcode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($httpcode != 200) {
	die("Unexpected status code: {$httpcode} | response: {$response}");
}

$presignedData = json_decode($response, true);
$presignedURL = $presignedData['data']['presigned_url'];
echo "Generated presigned URL: {$presignedURL}" . PHP_EOL;

// 7. Download the file using the presigned URL
$ch = curl_init($presignedURL);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

echo "Downloaded presigned URL data size: " . strlen($result) . PHP_EOL;
?>