README

Telnyx adapter for the BootDesk multi-platform messaging SDK. Supports SMS, MMS, and RCS.

Install

composer require bootdesk/chat-sdk-adapter-telnyx

Requires a PSR-18 HTTP client (guzzlehttp/guzzle, symfony/http-client, etc.) and a PSR-17 factory (nyholm/psr7 bundled).

Configuration

use BootDesk\ChatSDK\Telnyx\TelnyxAdapter;

$adapter = new TelnyxAdapter(
    apiKey: env('TELNYX_API_KEY'),
    httpClient: new \GuzzleHttp\Client,
    messagingProfileId: env('TELNYX_MESSAGING_PROFILE_ID'),
    publicKey: env('TELNYX_PUBLIC_KEY'),
    fromNumber: env('TELNYX_FROM_NUMBER'),
    agentId: env('TELNYX_AGENT_ID'),
);

Laravel

The ChatServiceProvider auto-binds Psr\Http\Client\ClientInterface to GuzzleHttp\Client. Add to config/chat.php:

'telnyx' => [
    'api_key' => env('TELNYX_API_KEY'),
    'messaging_profile_id' => env('TELNYX_MESSAGING_PROFILE_ID'),
    'public_key' => env('TELNYX_PUBLIC_KEY'),
    'from_number' => env('TELNYX_FROM_NUMBER'),
    'agent_id' => env('TELNYX_AGENT_ID'),
],

Override the HTTP client by setting http_client in config or rebinding ClientInterface in the container.

Sending Messages

The adapter auto-selects the endpoint based on whether agent_id is set:

• No agent_id → POST /v2/messages (SMS/MMS via long code, short code, or number pool)
• With agent_id → POST /v2/messages/rcs (RCS with SMS/MMS fallback)

SMS

$adapter->postMessage(
    'telnyx:+15551234567:+15559876543',
    PostableMessage::text('Hello from BootDesk!')
);

MMS

$adapter->postMessage(
    'telnyx:+15551234567:+15559876543',
    new PostableMessage(
        content: 'Check this out',
        attachments: [['url' => 'https://example.com/photo.jpg']],
    )
);

RCS (text)

$adapter = new TelnyxAdapter(
    apiKey: env('TELNYX_API_KEY'),
    httpClient: new \GuzzleHttp\Client,
    messagingProfileId: env('TELNYX_MESSAGING_PROFILE_ID'),
    agentId: 'e4448a5c...',
    fromNumber: '+15551234567',       // for SMS fallback
);

$adapter->postMessage(
    'telnyx:e4448a5c...:+15559876543',
    PostableMessage::text('Hello via RCS!')
);

RCS (rich card)

use BootDesk\ChatSDK\Core\Cards\Card;
use BootDesk\ChatSDK\Core\Cards\Button;

$card = Card::make()
    ->header('Special Offer')
    ->section(fn ($s) => $s->text('50% off today only'))
    ->image('https://example.com/banner.jpg')
    ->actions([
        Button::primary('Shop Now', 'action_shop'),
        Button::secondary('Dismiss', 'action_dismiss'),
    ]);

$adapter->postMessage(
    'telnyx:e4448a5c...:+15559876543',
    PostableMessage::card($card)
);

RCS fallback

When from_number is set and the first RCS message includes sms_fallback / mms_fallback, Telnyx may choose to send via SMS/MMS even if the recipient has RCS enabled — it depends on the carrier's capabilities at that moment. This means you might see RCS-fallback messages delivered as SMS for no apparent reason.

If you need strict RCS-only delivery (e.g., for rich cards, suggestions, or branding), register two separate Telnyx adapters:

$rcsAdapter = new TelnyxAdapter(
    apiKey: env('TELNYX_API_KEY'),
    httpClient: $client,
    messagingProfileId: env('TELNYX_MESSAGING_PROFILE_ID'),
    fromNumber: env('TELNYX_FROM_NUMBER'),
    agentId: env('TELNYX_RCS_AGENT_ID'),
    // No fromNumber — no fallback, RCS-only
);
$smsAdapter = new TelnyxAdapter(
    apiKey: env('TELNYX_API_KEY'),
    httpClient: $client,
    messagingProfileId: env('TELNYX_MESSAGING_PROFILE_ID'),
    fromNumber: env('TELNYX_FROM_NUMBER'),
    // No agentId — SMS/MMS-only
);

$chat->registerAdapter('rcs', $rcsAdapter);
$chat->registerAdapter('sms', $smsAdapter);

Then route based on $statusData['type'] === 'failed' in your onMessageFailed handler: retry via the SMS adapter.

RCS delivery reliability

RCS is a flaky protocol. Even when Telnyx accepts an RCS message (returns 200), the carrier may silently reject it or fail to deliver it. This is returned as a delivery_failed status event via HandlesStatuses. Key points:

• delivery_failed is normal and expected — do not treat it as a bug
• Always implement the onMessageFailed handler to trigger SMS fallback
• Some carriers/regions have no RCS support at all — all RCS messages will fail there
• Users may have RCS disabled on their device — messages fall back silently
• Read receipts (message.read) are not guaranteed — some users disable them
• SMS fallback (from_number) is recommended for production use

Feature Matrix

Documentationn

Full API documentation: https://bootdesk.github.io/chat-sdk

License

MIT