Texting Blue PHP SDK

Official PHP SDK for the Texting Blue API -- send and receive iMessage and SMS programmatically.

Requirements

• PHP 8.1+
• ext-curl
• ext-json

Installation

composer require textingblue/textingblue-php

Quick Start

<?php

require_once 'vendor/autoload.php';

use TextingBlue\TextingBlue;

$client = new TextingBlue('tb_live_xxx');

// Send a message
$message = $client->messages->send([
    'to'      => '+14155551234',
    'from'    => '+14155559876',
    'content' => 'Hello from Texting Blue!',
]);

echo $message['id']; // msg_xxx

Usage

Messages

// Send a message
$message = $client->messages->send([
    'to'      => '+14155551234',
    'from'    => '+14155559876',
    'content' => 'Hello!',
]);

// List messages
$messages = $client->messages->list(['limit' => 10]);

// Get a single message
$message = $client->messages->get('msg_xxx');

Numbers

// List all numbers
$numbers = $client->numbers->list();

// Get a single number
$number = $client->numbers->get('num_xxx');

// Update a number
$number = $client->numbers->update('num_xxx', ['label' => 'Support']);

// Delete a number
$client->numbers->delete('num_xxx');

Webhooks

// Create a webhook
$webhook = $client->webhooks->create([
    'url'    => 'https://yourapp.com/webhook',
    'events' => ['message.received'],
]);

// List webhooks
$webhooks = $client->webhooks->list();

// Get a single webhook
$webhook = $client->webhooks->get('wh_xxx');

// Update a webhook
$webhook = $client->webhooks->update('wh_xxx', [
    'events' => ['message.received', 'message.sent'],
]);

// Delete a webhook
$client->webhooks->delete('wh_xxx');

Webhook Verification

Verify incoming webhook signatures to ensure they are authentic:

use TextingBlue\Webhook;

$payload   = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_TEXTINGBLUE_SIGNATURE'] ?? '';
$secret    = 'whsec_xxx'; // from webhook creation response

// Option 1: Boolean check
$isValid = Webhook::verifySignature($payload, $signature, $secret);

// Option 2: Verify and parse in one step (throws on invalid signature)
try {
    $event = Webhook::constructEvent($payload, $signature, $secret);
    // handle $event
} catch (\TextingBlue\Exceptions\TextingBlueException $e) {
    http_response_code(400);
    exit('Invalid signature');
}

Available Resources

Resource	Methods
Messages	send, list, get
Numbers	list, get, update, delete
Webhooks	create, list, get, update, delete

Error Handling

All API errors throw typed exceptions:

use TextingBlue\Exceptions\ApiException;
use TextingBlue\Exceptions\AuthenticationException;
use TextingBlue\Exceptions\RateLimitException;

try {
    $client->messages->send([
        'to'      => '+14155551234',
        'from'    => '+14155559876',
        'content' => 'Hello!',
    ]);
} catch (AuthenticationException $e) {
    // Invalid API key (401)
    echo $e->getMessage();
} catch (RateLimitException $e) {
    // Too many requests (429)
    echo "Retry after: " . $e->getRetryAfter() . " seconds";
} catch (ApiException $e) {
    // Any other API error
    echo $e->getStatusCode();  // HTTP status code
    echo $e->getErrorCode();   // Machine-readable error code
    echo $e->getMessage();     // Human-readable message
    echo $e->getParam();       // Parameter that caused the error (if any)
}

Custom Base URL

For testing or self-hosted deployments:

$client = new TextingBlue('tb_live_xxx', 'https://api.staging.texting.blue/v1');

Other SDKs

• Node.js -- npm install @textingblue/node
• Python -- pip install textingblue

Links

• Homepage
• API Documentation
• Full Docs

License

MIT