README

A Laravel package for sending SMS messages using the iSend SMS API v3. Simple to use and easy to set up.

Key Features

• SMS messaging with single/multiple recipients
• Message scheduling and delivery tracking
• Campaign management
• Error handling with detailed diagnostics
• Interactive CLI setup wizard

Requirements

• PHP 8.2 or higher
• Laravel 11.x or 12.x
• Guzzle HTTP client
• Valid iSend SMS API credentials

Installation

You can install the package via Composer:

composer require isend/laravel

The package will automatically register itself using Laravel's package discovery.

Configuration

Interactive Setup (Recommended)

The easiest way to set up the package is by using the interactive setup command:

php artisan isend:setup

This command will set up your API credentials and publish the config file in one step.

Or, Manual Configuration

Alternatively, you can manually publish the configuration file:

php artisan vendor:publish --tag="isend-config"

This will create a config/isend.php file with comprehensive configuration options.

Then, add these environment variables to your .env file:

ISEND_API_TOKEN=your-api-token
ISEND_DEFAULT_SENDER_ID=your-sender-id

Optional Environment Variables

You can customize the service with these additional variables:

ISEND_BASE_URL=https://isend.com.ly
ISEND_API_VERSION_PATH=/api/v3

Basic Usage

Sending a Simple SMS

use ISend\SMS\Facades\ISend;

// Fluent interface
ISend::to('218929000834')
    ->message('Your verification code is 1234')
    ->send();

// Get the SMS ID for tracking
$smsId = ISend::to('218929000834')
    ->message('Your verification code is 1234')
    ->send()
    ->getId();

// Static helper method
ISend::sendSms('218929000834', 'Your verification code is 1234');

Multiple Recipients

// Send the same message to multiple recipients
ISend::to(['218929000834', '218929000836', '218929000837'])
    ->message('Important announcement for all users')
    ->send();

// Or as a comma-separated string
ISend::to('218929000834,218929000836,218929000837')
    ->message('Important announcement for all users')
    ->send();

Custom Sender ID

ISend::to('218929000834')
    ->from('MyApp')  // Override the default sender ID
    ->message('Your verification code is 1234')
    ->send();

Scheduled Messages

// Schedule a message for future delivery
ISend::to('218929000834')
    ->message('Reminder: Your appointment is tomorrow')
    ->scheduleAt('2025-12-31 09:00:00')  // Format: Y-m-d H:i
    ->send();

DLT Template ID (for regulatory compliance)

// For regions requiring DLT template registration
ISend::to('218929000834')
    ->message('Your OTP is 1234')
    ->dltTemplateId('template-123')
    ->send();

Advanced Features

Checking Message Status

// Get the status of a sent message using its ID
$status = ISend::getStatus('sms-uid-123456');

// Example response structure
[
    'status' => 'success',
    'data' => [
        'uid' => 'sms-uid-123456',
        'status' => 'delivered',
        'sent_at' => '2025-01-01 12:00:00',
        'delivered_at' => '2025-01-01 12:00:05',
        // Additional status details...
    ]
]

Listing Messages

// Get a list of all sent messages
$messages = ISend::listMessages();

Campaign Management

// Send a campaign to a contact list
$campaign = ISend::sendCampaign(
    'contact-list-123',
    'Special offer for our valued customers!',
    'Marketing',  // Optional custom sender ID
    '2025-02-15 08:00:00'  // Optional schedule time
);

// Send to multiple contact lists
$campaign = ISend::sendCampaign(
    ['list-123', 'list-456'],
    'Special offer for all our customers!'
);

Account Management

// Get profile information
$profile = ISend::getProfile();

// Check account balance
$balance = ISend::checkBalance();

// Get registered sender IDs
$senderIds = ISend::getSenderIds();

// Get transaction history
$transactions = ISend::getTransactions();

Exception Handling

The package throws ISendException with detailed error information:

use ISend\SMS\Exceptions\ISendException;

try {
    ISend::to('invalid-number')
        ->message('Test message')
        ->send();
} catch (ISendException $e) {
    // Basic error information
    $message = $e->getMessage();
    $statusCode = $e->getStatusCode();
    
    // Detailed error data
    $responseData = $e->getResponseData();  // Full API response
    $requestData = $e->getRequestData();    // The request that caused the error
    
    // Error type helpers
    if ($e->isAuthenticationError()) {
        // Handle 401 errors (invalid API token)
    }
    
    if ($e->isValidationError()) {
        // Handle 422 errors (invalid parameters)
    }
    
    if ($e->isServerError()) {
        // Handle 5xx errors (server issues)
    }
    
    // Get complete error details as array
    $errorDetails = $e->toArray();
    
    // Log the error or handle as needed...
}

Debugging

For debugging purposes, you can access the last API response:

$response = ISend::to('218929000834')
    ->message('Test message')
    ->send()
    ->getLastResponse();

Testing

The package includes a comprehensive test suite:

composer test

Laravel Version Compatibility

Security

If you discover any security issues, please email soliman.benhalim@gmail.com instead of using the issue tracker.

Credits

• iSend SMS Service

License

The MIT License (MIT). Please see License File for more information.