README

Laravel SDK for SignalBridge SMS Gateway - Send SMS messages through multiple vendors (SpeedaMobile, Africa's Talking) with a unified API. Built specifically for Nugsoft product/project teams.

Features

Simple API - Clean, Laravel-style interface
Balance Management - Check balance, view transactions, get usage reports
Scheduled Messages - Schedule SMS for future delivery
Segment Calculation - Automatic cost estimation (GSM 7-bit vs Unicode)
Custom Exceptions - Typed exceptions for better error handling
Facade Support - Use SignalBridge::sendSms() syntax
Dependency Injection - Constructor injection support
Laravel 10, 11, 12 - Compatible with modern Laravel versions
PHP 8.1+ - Modern PHP features
Queue - Supports message queueing for reliable delivery with retry logic and monitoring via Laravel's queue system

Requirements

PHP 8.1 or higher
Laravel 10.0, 11.0, or 12.0
Guzzle HTTP 7.0+

Installation

1. Install via Composer

composer require nugsoft/signalbridge-laravel-sdk

2. Publish Configuration (Optional)

php artisan vendor:publish --tag=signalbridge-config

This creates config/signalbridge.php where you can customize settings.

3. Configure Environment Variables

Add these to your .env file:

SIGNALBRIDGE_TOKEN=your_api_token_here

Getting Your API Token:

Contact your system administrator or generate a token via:

curl -X POST https://signal-bridge.nugsoftstagging.com/api/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-product@nugsoft.com",
    "password": "your-password",
    "expires_in_days": 365
  }'

Note

You can also generate your token through the SignalBridge settings page in your account.

Usage

Quick Start

Using the Facade (Recommended)

use Nugsoft\SignalBridge\Facades\SignalBridge;

// Send SMS
$result = SignalBridge::sendSms(
    recipient: '256700000000',
    message: 'Hello from Laravel!',
    options: [
        'metadata' => ['user_id' => 123]
    ]
);

Using Dependency Injection

use Nugsoft\SignalBridge\SignalBridgeClient;

class NotificationService
{
    public function __construct(
        private SignalBridgeClient $signalBridge
    ) {}

    public function sendWelcomeSms(string $phone, string $name)
    {
        return $this->signalBridge->sendSms(
            recipient: $phone,
            message: "Welcome {$name}! Thanks for joining us."
        );
    }
}

Real-World Examples

1. Send OTP/Verification Code

use Nugsoft\SignalBridge\Facades\SignalBridge;
use Illuminate\Support\Facades\Cache;

public function sendOTP(Request $request)
{
    $code = rand(100000, 999999);

    // Store in cache for 5 minutes
    Cache::put("otp:{$request->phone}", $code, now()->addMinutes(5));

    try {
        $result = SignalBridge::sendSms(
            recipient: $request->phone,
            message: "Your verification code is {$code}. Valid for 5 minutes.",
            options: [
                'metadata' => [
                    'user_id' => $request->user()->id,
                    'action' => 'otp_verification',
                    'ip_address' => $request->ip(),
                ]
            ]
        );

        return response()->json([
            'success' => true,
            'message' => 'OTP sent successfully',
            'cost' => $result['data']['cost'],
        ]);

    } catch (\Nugsoft\SignalBridge\Exceptions\InsufficientBalanceException $e) {
        return response()->json([
            'success' => false,
            'message' => 'Insufficient balance',
            'required' => $e->getRequiredBalance(),
            'available' => $e->getCurrentBalance(),
        ], 402);
    }
}

2. Batch SMS Notifications

use Nugsoft\SignalBridge\Facades\SignalBridge;

public function notifyStudents(Request $request)
{
    $students = $request->input('students'); // Array of student data

    // Build batch messages
    $messages = collect($students)->map(function ($student) {
        return [
            'recipient' => $student['phone'],
            'message' => "Hi {$student['name']}, your exam results are ready. Score: {$student['score']}/100",
            'metadata' => [
                'student_id' => $student['id'],
                'exam_id' => $request->exam_id,
            ]
        ];
    })->toArray();

    try {
        $result = SignalBridge::sendBatch($messages);

        return response()->json([
            'success' => true,
            'sent' => $result['data']['successful'],
            'failed' => $result['data']['failed'],
        ]);

    } catch (\Nugsoft\SignalBridge\Exceptions\ValidationException $e) {
        return response()->json([
            'success' => false,
            'errors' => $e->getErrors(),
        ], 422);
    }
}

3. Scheduled Reminders

use Nugsoft\SignalBridge\Facades\SignalBridge;
use Carbon\Carbon;

public function schedulePaymentReminders()
{
    $invoices = Invoice::whereDue(today()->addDay())->get();

    $messages = $invoices->map(function ($invoice) {
        return [
            'recipient' => $invoice->customer_phone,
            'message' => "Reminder: Invoice #{$invoice->number} of {$invoice->amount} UGX is due tomorrow.",
            'scheduled_at' => Carbon::tomorrow()->setTime(9, 0)->toIso8601String(),
            'metadata' => [
                'invoice_id' => $invoice->id,
                'type' => 'payment_reminder',
            ]
        ];
    })->toArray();

    return SignalBridge::sendBatch($messages);
}

4. Balance Check Before Sending

use Nugsoft\SignalBridge\Facades\SignalBridge;

public function sendBulkWithValidation(array $recipients, string $message)
{
    // Get current balance
    $balance = SignalBridge::getBalance('UGX');

    // Calculate cost
    $segments = SignalBridge::calculateSegments($message);
    $estimatedCost = count($recipients) * $segments * $balance['segment_price'];

    // Validate sufficient balance
    if ($balance['available_balance'] < $estimatedCost) {
        throw new \Exception(
            "Insufficient balance. Required: {$estimatedCost}, Available: {$balance['available_balance']}"
        );
    }

    // Proceed with sending
    $messages = collect($recipients)->map(fn($phone) => [
        'recipient' => $phone,
        'message' => $message,
    ])->toArray();

    return SignalBridge::sendBatch($messages);
}

5. Usage Reporting

use Nugsoft\SignalBridge\Facades\SignalBridge;

public function getMonthlyReport(string $month)
{
    $startDate = Carbon::parse($month)->startOfMonth()->format('Y-m-d');
    $endDate = Carbon::parse($month)->endOfMonth()->format('Y-m-d');

    $transactions = SignalBridge::getTransactions([
        'type' => 'debit',
        'start_date' => $startDate,
        'end_date' => $endDate,
        'per_page' => 100,
    ]);

    // Group by message type
    $summary = collect($transactions['data'])
        ->groupBy(fn($tx) => $tx['metadata']['type'] ?? 'general')
        ->map(fn($group) => [
            'count' => $group->count(),
            'cost' => $group->sum('amount'),
        ]);

    return [
        'period' => $month,
        'total_cost' => collect($transactions['data'])->sum('amount'),
        'by_type' => $summary,
    ];
}

API Reference

Send SMS

SignalBridge::sendSms(
    recipient: '256700000000',
    message: 'Your message here',
    options: [
        'metadata' => [],                   // Optional: Custom data
        'is_test' => false,                 // Optional: Test mode flag
        'scheduled_at' => '2025-12-01...',  // Optional: ISO 8601 datetime
    ]
);

Returns:

[
    'success' => true,
    'message' => 'SMS queued successfully',
    'data' => [
        'message_id' => 1234,
        'status' => 'queued',
        'vendor' => 'SpeedaMobile',
        'segments' => 1,
        'cost' => 75.00,
        'balance_after' => 9925.00
    ]
]

Send Batch SMS

SignalBridge::sendBatch(
    messages: [
        [
            'recipient' => '256700000000',
            'message' => 'Message 1',
            'metadata' => ['order_id' => 123]
        ],
        [
            'recipient' => '256700000001',
            'message' => 'Message 2',
            'metadata' => ['order_id' => 124]
        ],
    ],
    options: [
        'is_test' => false,
    ]
);

Returns:

[
    'success' => true,
    'message' => 'Batch SMS processed: 2 successful, 0 failed',
    'data' => [
        'total' => 2,
        'successful' => 2,
        'failed' => 0,
        'messages' => [...]
    ]
]

Get Balance

$balance = SignalBridge::getBalance('UGX');

Returns:

[
    'success' => true,
    'balance' => 100.00,
    'currency' => 'UGX',
    'available_balance' => 100.00,
    'credit_limit' => 0.00,
    'segment_price' => 0.02
]

Get Balance Summary

$summary = SignalBridge::getBalanceSummary();

Get Transactions

$transactions = SignalBridge::getTransactions([
    'per_page' => 15,
    'page' => 1,
    'type' => 'debit',
    'start_date' => '2025-11-01',
    'end_date' => '2025-11-30',
]);

Calculate Segments

$segments = SignalBridge::calculateSegments('Your message here');
// Returns: 1 (for messages up to 160 GSM chars or 70 Unicode chars)

Estimate Cost

$cost = SignalBridge::estimateCost(
    message: 'Your message here',
    segmentPrice: 0.02
);
// Returns: 0.02 (segments * price)

Token Management

// Get all tokens
$tokens = SignalBridge::getTokens();

// Revoke current token
$result = SignalBridge::revokeCurrentToken();

Exception Handling

The SDK provides typed exceptions for better error handling:

use Nugsoft\SignalBridge\Exceptions\InsufficientBalanceException;
use Nugsoft\SignalBridge\Exceptions\ValidationException;
use Nugsoft\SignalBridge\Exceptions\NoClientException;
use Nugsoft\SignalBridge\Exceptions\ServiceUnavailableException;
use Nugsoft\SignalBridge\Exceptions\SignalBridgeException;

try {
    SignalBridge::sendSms('256700000000', 'Test message');

} catch (InsufficientBalanceException $e) {
    // Handle insufficient balance
    $required = $e->getRequiredBalance();
    $current = $e->getCurrentBalance();
    $segments = $e->getSegments();

} catch (ValidationException $e) {
    // Handle validation errors
    $errors = $e->getErrors();
    $firstError = $e->getFirstError();

} catch (NoClientException $e) {
    // Handle no client associated

} catch (ServiceUnavailableException $e) {
    // Handle service unavailable (no SMS vendor configured)

} catch (SignalBridgeException $e) {
    // Handle other API errors
    $data = $e->getData();
}

SMS Segments & Pricing

Messages are charged based on segments:

GSM 7-bit Encoding (standard characters):

Single segment: Up to 160 characters
Multi-part: 153 characters per segment

Unicode Encoding (emojis, Arabic, Chinese, etc.):

Single segment: Up to 70 characters
Multi-part: 67 characters per segment

The SDK automatically detects encoding and calculates segments.

Configuration

After publishing the config file, you can customize:

// config/signalbridge.php

return [
    'url' => env('SIGNALBRIDGE_URL', 'https://signal-bridge.nugsoftstagging.com/api'),
    'token' => env('SIGNALBRIDGE_TOKEN'),
    'timeout' => env('SIGNALBRIDGE_TIMEOUT', 30),
    'default_sender_id' => env('SIGNALBRIDGE_SENDER_ID', config('app.name')),
    'logging' => env('SIGNALBRIDGE_LOGGING', true),
];

Testing

composer test

License

The MIT License (MIT). This package is proprietary to Nugsoft.

Credits

Asaba William
Nugsoft Dev team

Made with ❤️ by Nugsoft

nugsoft / signalbridge-laravel-sdk

Maintainers

Details

README

Features

Requirements

Installation

1. Install via Composer

2. Publish Configuration (Optional)

3. Configure Environment Variables

Usage

Quick Start

Using the Facade (Recommended)

Using Dependency Injection

Real-World Examples

1. Send OTP/Verification Code

2. Batch SMS Notifications

3. Scheduled Reminders

4. Balance Check Before Sending

5. Usage Reporting

API Reference

Send SMS

Send Batch SMS

Get Balance

Get Balance Summary

Get Transactions

Calculate Segments

Estimate Cost

Token Management

Exception Handling

SMS Segments & Pricing

Configuration

Testing

License

Credits