openbackend/nepali-sms

A comprehensive Laravel package for integrating popular Nepali SMS gateways including Sparrow SMS, Sparrow A2P, Ebeema, EasySMS and more

v1.1.1 2025-07-29 20:05 UTC

This package is auto-updated.

Last update: 2025-07-29 20:07:48 UTC


README

Latest Version on Packagist Total Downloads License

A comprehensive Laravel package for integrating popular Nepali SMS gateways with advanced features like OTP verification, bulk messaging, delivery tracking, and more.

Supported SMS Gateways

  • Sparrow SMS - Popular SMS gateway in Nepal
  • Sparrow A2P - Application-to-Person messaging
  • Ebeema SMS - Reliable SMS service provider
  • EasySMS - Simple SMS integration
  • SMS24x7 - 24/7 SMS service
  • Custom Gateway - Add your own SMS provider

Features

  • 🚀 Multiple Gateway Support - Switch between different SMS providers
  • 📱 OTP Generation & Verification - Built-in OTP system with expiration
  • 📊 Delivery Tracking - Track message delivery status
  • 🔄 Queue Support - Send SMS asynchronously using Laravel queues
  • 📈 Bulk Messaging - Send messages to multiple recipients
  • 🎯 Template Support - Pre-defined message templates
  • 📝 Logging - Comprehensive logging for debugging
  • 🔒 Rate Limiting - Prevent abuse with configurable rate limits
  • 📊 Analytics - SMS sending statistics and reports
  • 🌐 Multi-language - Support for English and Nepali text
  • 🔄 Failover - Automatic fallback to backup gateways
  • 📱 Laravel Notifications - Integration with Laravel notification system

Requirements

  • PHP 8.1 or higher
  • Laravel 10.0 or higher (supports Laravel 12)

Installation

Install the package via Composer:

composer require openbackend/nepali-sms

Publish the configuration file:

php artisan vendor:publish --provider="OpenBackend\NepaliSms\NepaliSmsServiceProvider"

Run the migrations to create necessary tables:

php artisan migrate

Configuration

Configure your SMS gateways in config/nepali-sms.php:

return [
    'default' => env('NEPALI_SMS_DEFAULT_GATEWAY', 'sparrow'),
    
    'gateways' => [
        'sparrow' => [
            'driver' => 'sparrow',
            'token' => env('SPARROW_SMS_TOKEN'),
            'from' => env('SPARROW_SMS_FROM', 'SPARROW'),
        ],
        
        'sparrow_a2p' => [
            'driver' => 'sparrow_a2p',
            'client_id' => env('SPARROW_A2P_CLIENT_ID'),
            'client_secret' => env('SPARROW_A2P_CLIENT_SECRET'),
            'from' => env('SPARROW_A2P_FROM'),
        ],
        
        'ebeema' => [
            'driver' => 'ebeema',
            'username' => env('EBEEMA_USERNAME'),
            'password' => env('EBEEMA_PASSWORD'),
            'from' => env('EBEEMA_FROM'),
        ],
    ],
    
    'otp' => [
        'length' => 6,
        'expiry' => 300, // 5 minutes
        'template' => 'Your OTP code is: {otp}. Valid for {expiry} minutes.',
    ],
    
    'rate_limit' => [
        'enabled' => true,
        'max_attempts' => 5,
        'decay_minutes' => 1,
    ],
];

Add your gateway credentials to .env:

NEPALI_SMS_DEFAULT_GATEWAY=sparrow

# Sparrow SMS
SPARROW_SMS_TOKEN=your_sparrow_token
SPARROW_SMS_FROM=YourApp

# Sparrow A2P
SPARROW_A2P_CLIENT_ID=your_client_id
SPARROW_A2P_CLIENT_SECRET=your_client_secret
SPARROW_A2P_FROM=YourApp

# Ebeema SMS
EBEEMA_USERNAME=your_username
EBEEMA_PASSWORD=your_password
EBEEMA_FROM=YourApp

Basic Usage

Sending a Simple SMS

use OpenBackend\NepaliSms\Facades\NepaliSms;

// Send SMS using default gateway
NepaliSms::to('9841234567')
    ->message('Hello from Nepal!')
    ->send();

// Send SMS using specific gateway
NepaliSms::gateway('sparrow')
    ->to('9841234567')
    ->message('Hello from Sparrow!')
    ->send();

Sending Bulk SMS

$recipients = ['9841234567', '9851234567', '9861234567'];

NepaliSms::to($recipients)
    ->message('Bulk message to all recipients')
    ->send();

OTP Generation and Verification

// Generate and send OTP
$otp = NepaliSms::generateOtp('9841234567');

// Verify OTP
$isValid = NepaliSms::verifyOtp('9841234567', '123456');

if ($isValid) {
    // OTP is valid
} else {
    // Invalid or expired OTP
}

Using Templates

// Create a template
NepaliSms::createTemplate('welcome', 'Welcome {name} to our platform!');

// Send using template
NepaliSms::to('9841234567')
    ->template('welcome', ['name' => 'John'])
    ->send();

Queue Support

// Send SMS asynchronously
NepaliSms::to('9841234567')
    ->message('This will be sent via queue')
    ->queue();

// Send with delay
NepaliSms::to('9841234567')
    ->message('This will be sent after 5 minutes')
    ->delay(now()->addMinutes(5))
    ->queue();

Advanced Features

Laravel Notifications Integration

Create a notification class:

php artisan make:notification WelcomeMessage
use OpenBackend\NepaliSms\Channels\NepaliSmsChannel;
use OpenBackend\NepaliSms\Messages\NepaliSmsMessage;

class WelcomeMessage extends Notification
{
    public function via($notifiable)
    {
        return [NepaliSmsChannel::class];
    }

    public function toNepaliSms($notifiable)
    {
        return NepaliSmsMessage::create()
            ->message('Welcome to our platform!')
            ->gateway('sparrow');
    }
}

Send notification:

$user->notify(new WelcomeMessage());

Delivery Tracking

$message = NepaliSms::to('9841234567')
    ->message('Track this message')
    ->send();

// Check delivery status
$status = NepaliSms::getDeliveryStatus($message->id);

// Get detailed delivery report
$report = NepaliSms::getDeliveryReport($message->id);

Analytics and Reports

// Get SMS statistics for today
$stats = NepaliSms::getStatistics();

// Get statistics for specific date range
$stats = NepaliSms::getStatistics(
    from: now()->subDays(7),
    to: now()
);

// Get gateway-wise statistics
$gatewayStats = NepaliSms::getGatewayStatistics('sparrow');

Rate Limiting

// Check if user can send SMS
if (NepaliSms::canSendSms('9841234567')) {
    NepaliSms::to('9841234567')
        ->message('Rate limited message')
        ->send();
} else {
    // Rate limit exceeded
}

Failover Support

// Configure multiple gateways with priority
NepaliSms::gateways(['sparrow', 'ebeema', 'easysms'])
    ->to('9841234567')
    ->message('This will try multiple gateways if one fails')
    ->send();

Artisan Commands

Test SMS Gateway

php artisan nepali-sms:test --gateway=sparrow --to=9841234567

Generate OTP

php artisan nepali-sms:otp --generate --phone=9841234567

Verify OTP

php artisan nepali-sms:otp --verify --phone=9841234567 --code=123456

View Statistics

php artisan nepali-sms:stats

Clear Old SMS Logs

php artisan nepali-sms:cleanup --days=30

Events

The package fires several events that you can listen to:

  • MessageSending - Before sending SMS
  • MessageSent - After SMS is sent successfully
  • MessageFailed - When SMS sending fails
  • OtpGenerated - When OTP is generated
  • OtpVerified - When OTP is verified
  • OtpExpired - When OTP expires

Example listener:

Event::listen(MessageSent::class, function ($event) {
    Log::info('SMS sent successfully', [
        'to' => $event->message->to,
        'gateway' => $event->message->gateway,
        'id' => $event->message->id,
    ]);
});

Testing

Run the test suite:

composer test

Run tests with coverage:

composer test-coverage

Security

If you discover any security-related issues, please email security@openbackend.dev instead of using the issue tracker.

Contributing

Please see CONTRIBUTING.md for details.

License

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

Credits

Support