PHPackages                             warrenfox002/reach-interactive-sms-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. warrenfox002/reach-interactive-sms-api

ActiveLibrary[API Development](/categories/api)

warrenfox002/reach-interactive-sms-api
======================================

Reach Interactive SMS API - PHP client library

01PHP

Since Jun 15Pushed 1mo agoCompare

[ Source](https://github.com/Warrenfox002/Reach-Interactive-SMS-API-Client)[ Packagist](https://packagist.org/packages/warrenfox002/reach-interactive-sms-api)[ RSS](/packages/warrenfox002-reach-interactive-sms-api/feed)WikiDiscussions main Synced 2w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Reach Interactive SMS API PHP Client
====================================

[](#reach-interactive-sms-api-php-client)

[![Latest Stable Version](https://camo.githubusercontent.com/3e5dba6c7d83ccdc1d28557cdfb02c670454e463d03f7791c4e8a3f36f2f52d5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f57617272656e466f783030322f72656163682d696e7465726163746976652d736d732d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/WarrenFox002/reach-interactive-sms-api)[![Total Downloads](https://camo.githubusercontent.com/06a2527a6c1b0b5d41076cb4f992e03dde3d9a752c54631c5b45436538ffae8d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f57617272656e466f783030322f72656163682d696e7465726163746976652d736d732d6170692e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/WarrenFox002/reach-interactive-sms-api)[![License](https://camo.githubusercontent.com/55c0218c8f8009f06ad4ddae837ddd05301481fcf0dff8e0ed9dadda8780713e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d627269676874677265656e2e7376673f7374796c653d666c61742d737175617265)](LICENSE)[![PHP Version](https://camo.githubusercontent.com/d332c02139e0abd65c7c603532e2abdeca3fa33577802313a9d1f5d42633971b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344382e302d3838393242462e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/WarrenFox002/reach-interactive-sms-api)

A comprehensive and easy-to-use PHP client library for the [Reach Interactive SMS API](https://www.reach-interactive.com/sms-api/api). Send SMS messages, check account balance, manage scheduled messages, and handle errors with typed exceptions.

Features
--------

[](#features)

✅ Full SMS API implementation
✅ Typed exception handling for all error scenarios
✅ JWT token authentication support
✅ Basic authentication via username/password
✅ Send single or bulk SMS messages (up to 50 per request)
✅ Retrieve message status and details
✅ Delete scheduled messages
✅ Check account balance
✅ Delivery report callbacks
✅ Comprehensive error handling
✅ PSR-4 autoloading
✅ PHP 8.0+

Installation
------------

[](#installation)

Install via Composer:

```
composer require warrenfox002/reach-interactive-sms-api
```

Quick Start
-----------

[](#quick-start)

### Basic Usage

[](#basic-usage)

```
use ReachInteractive\ReachInteractiveAPI;
use ReachInteractive\Exceptions\ReachInteractiveException;

// Initialize the API client
$api = new ReachInteractiveAPI('your_username', 'your_password');

try {
    // Send a message
    $result = $api->sendMessage(
        to: '447xxxxxxxxx',
        from: 'YourSender',
        message: 'Hello! This is a test message.'
    );

    echo "Message ID: " . $result[0]['Id'];
} catch (ReachInteractiveException $e) {
    echo "Error: " . $e->getMessage();
}
```

### Check Account Balance

[](#check-account-balance)

```
try {
    $balance = $api->getBalance();
    echo "Balance: " . $balance['Balance'];
} catch (ReachInteractiveException $e) {
    echo "Error: " . $e->getMessage();
}
```

### Send to Multiple Recipients

[](#send-to-multiple-recipients)

```
$phones = ['447xxxxxxxxx', '447yyyyyyyyy', '447zzzzzzzzz'];

$result = $api->sendMessage(
    to: $phones,
    from: 'YourSender',
    message: 'Bulk message'
);

echo "Sent to " . count($result) . " recipients";
```

### Advanced Options

[](#advanced-options)

```
$result = $api->sendMessage(
    to: '447xxxxxxxxx',
    from: 'YourSender',
    message: 'Scheduled message',
    options: [
        'reference' => 'ORDER-12345',
        'valid' => 24,  // Retry for 24 hours
        'scheduled' => '2024/06/20 14:30',
        'callbackurl' => 'https://yourdomain.com/sms-callback',
        'coding' => 1  // 1=Text, 2=Unicode, 3=Binary
    ]
);
```

Exception Handling
------------------

[](#exception-handling)

The library provides specific exception types for different error scenarios:

```
use ReachInteractive\ReachInteractiveAPI;
use ReachInteractive\Exceptions\{
    ReachInteractiveException,
    ReachInteractiveAuthenticationException,
    ReachInteractiveInsufficientCreditsException,
    ReachInteractiveBadRequestException,
    ReachInteractiveServiceException
};

try {
    $result = $api->sendMessage(
        to: '447xxxxxxxxx',
        from: 'YourSender',
        message: 'Test'
    );
} catch (ReachInteractiveAuthenticationException $e) {
    // Handle authentication error (401)
    echo "Invalid credentials";
} catch (ReachInteractiveInsufficientCreditsException $e) {
    // Handle credit error (402)
    echo "Out of credits";
} catch (ReachInteractiveBadRequestException $e) {
    // Handle validation error (400)
    echo "Invalid parameters";
} catch (ReachInteractiveServiceException $e) {
    // Handle service error (5xx)
    echo "Service error";
} catch (ReachInteractiveException $e) {
    // Handle all other errors
    echo "API error: " . $e->getMessage();
}
```

Available Methods
-----------------

[](#available-methods)

### `getBalance(): array`

[](#getbalance-array)

Retrieve your account balance and credit information.

```
$balance = $api->getBalance();
// Returns: ['Success' => true, 'Balance' => 123.45, 'Description' => '...']
```

### `sendMessage(string|array $to, string $from, string $message, array $options = []): array`

[](#sendmessagestringarray-to-string-from-string-message-array-options---array)

Send SMS message(s) to one or more recipients.

```
$result = $api->sendMessage(
    to: '447xxxxxxxxx',  // or array of numbers
    from: 'YourSender',
    message: 'Your message',
    options: [
        'reference' => 'custom-ref',
        'valid' => 72,
        'scheduled' => '2024/06/20 14:30',
        'callbackurl' => 'https://yourdomain.com/callback',
        'coding' => 1
    ]
);
```

### `getMessageDetails(string $messageId): array`

[](#getmessagedetailsstring-messageid-array)

Get details about a previously sent message.

```
$details = $api->getMessageDetails('message-uuid');
```

### `deleteMessage(string $messageId): array`

[](#deletemessagestring-messageid-array)

Delete a scheduled message that hasn't been sent yet.

```
$result = $api->deleteMessage('message-uuid');
```

### `generateJWTToken(int $expiresMinutes = 60): string`

[](#generatejwttokenint-expiresminutes--60-string)

Generate a JWT token for authentication (alternative to basic auth).

```
$token = $api->generateJWTToken(expiresMinutes: 60);
// Subsequent requests automatically use JWT authentication
```

### `isJWTTokenValid(): bool`

[](#isjwttokenvalid-bool)

Check if the current JWT token is still valid.

```
if ($api->isJWTTokenValid()) {
    echo "JWT token is valid";
}
```

### `setRequestTimeout(int $seconds): void`

[](#setrequesttimeoutint-seconds-void)

Set custom timeout for API requests (default: 30 seconds).

```
$api->setRequestTimeout(60);
```

Error Codes
-----------

[](#error-codes)

The API uses standard HTTP status codes:

CodeStatusException200OK-400Bad Request`ReachInteractiveBadRequestException`401Unauthorized`ReachInteractiveAuthenticationException`402Payment Required`ReachInteractiveInsufficientCreditsException`403Forbidden`ReachInteractiveForbiddenException`500Server Error`ReachInteractiveServiceException`503Service Unavailable`ReachInteractiveUnavailableException`DLR Codes (Delivery Reports)
----------------------------

[](#dlr-codes-delivery-reports)

CodeStatus000Delivered600No credits to send601No route602Blacklisted number detected603Bad destination number604Bad source number605Target SMSC message queue606Target SMSC submit fail607General error608Spam message detected609Validity period expired610Unauthorised Source address611Unknown DLR code612Submit timeoutDelivery Reports
----------------

[](#delivery-reports)

Configure callback URL to receive delivery reports:

```
$api->sendMessage(
    to: '447xxxxxxxxx',
    from: 'YourSender',
    message: 'Message',
    options: [
        'callbackurl' => 'https://yourdomain.com/sms-callback'
    ]
);
```

The callback will receive GET requests with parameters:

- `MsgId`: Message ID
- `MSISDN`: Recipient number
- `Timestamp`: Delivery timestamp
- `Status`: Status (delivered, rejected, expired, undelivered)
- `Code`: DLR code

Configuration
-------------

[](#configuration)

### Authentication

[](#authentication)

**Basic Auth (Default)**

```
$api = new ReachInteractiveAPI('username', 'password');
```

**JWT Token Auth**

```
$api = new ReachInteractiveAPI('username', 'password');
$token = $api->generateJWTToken(expiresMinutes: 120);
```

### Request Timeout

[](#request-timeout)

```
$api->setRequestTimeout(60); // 60 seconds
```

Requirements
------------

[](#requirements)

- PHP 8.0 or higher
- cURL extension
- JSON extension

Best Practices
--------------

[](#best-practices)

1. **Always handle exceptions** - API calls can fail for various reasons
2. **Use JWT tokens** - More secure than basic auth for production
3. **Implement retry logic** - Handle 503 Service Unavailable errors gracefully
4. **Validate inputs** - Check phone numbers and message content before sending
5. **Log errors** - Keep detailed logs for troubleshooting and auditing
6. **Monitor balance** - Set up alerts for low credit balance
7. **Batch operations** - Use bulk sending (up to 50 recipients per request)
8. **Test first** - Send test messages before bulk operations

Example Integration
-------------------

[](#example-integration)

```