README

Laravel integration for MSG91 SMS and OTP services. This package provides a seamless Laravel integration for the kaydee123/msg91-php package.

Features

• Send SMS messages (single and bulk)
• Send OTP via SMS
• Verify OTP codes
• Retry/Resend OTP (text or voice)
• Template-based SMS support
• DLT compliance support for India
• Comprehensive error handling
• Laravel Service Provider with auto-discovery
• Facade support for easy access
• Helper functions
• Publishable configuration file

Requirements

• PHP 8.0 to 8.5
• Laravel 8.x, 9.x, 10.x, 11.x, or 12.x
• Composer
• MSG91 account with API credentials

Installation

Install the package via Composer:

composer require kaydee123/msg91-laravel

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

Configuration

Publish Configuration File

Publish the configuration file to customize settings:

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

This will create a config/msg91.php file in your Laravel application.

Environment Variables

Add your MSG91 Auth Key to your .env file:

MSG91_AUTH_KEY=your_auth_key_here
MSG91_BASE_URL=https://control.msg91.com/api/
MSG91_TIMEOUT=30
MSG91_DEBUG=false

You can get your MSG91 Auth Key from your MSG91 Dashboard.

Usage

Using the Facade

The package provides a Msg91 facade for easy access:

use Kaydee123\Msg91Laravel\Facades\Msg91;

// Send SMS using Template
$response = Msg91::sms()
    ->template('YOUR_TEMPLATE_ID')
    ->variables(['number' => '3', 'date' => '22-12-2025'])
    ->numbers('919876543210')
    ->send();

// Send OTP
$response = Msg91::otp()
    ->template('YOUR_OTP_TEMPLATE_ID')
    ->number('919876543210')
    ->send();

// Verify OTP
$response = Msg91::otp('123456')
    ->number('919876543210')
    ->verify();

Using Dependency Injection

You can inject the Msg91Client directly into your controllers or services:

use Kaydee123\Msg91\Msg91Client;

class SmsController extends Controller
{
    protected $msg91;

    public function __construct(Msg91Client $msg91)
    {
        $this->msg91 = $msg91;
    }

    public function sendSms()
    {
        $response = $this->msg91->sms()
            ->template('YOUR_TEMPLATE_ID')
            ->numbers('919876543210')
            ->send();
    }
}

Using Helper Function

You can also use the msg91() helper function:

// Send SMS
$response = msg91()->sms()
    ->template('YOUR_TEMPLATE_ID')
    ->variables(['var1' => 'value1'])
    ->numbers('919876543210')
    ->send();

// Send OTP
$response = msg91()->otp()
    ->template('YOUR_OTP_TEMPLATE_ID')
    ->number('919876543210')
    ->send();

Using the Service Container

You can resolve the client from the service container:

$msg91 = app('msg91.client');

// Or using the class name
$msg91 = app(\Kaydee123\Msg91\Msg91Client::class);

Examples

SMS Examples

Send SMS using Template (Recommended):

use Kaydee123\Msg91Laravel\Facades\Msg91;

$response = Msg91::sms()
    ->template('YOUR_TEMPLATE_ID')
    ->variables(['number' => '3', 'date' => '22-12-2025'])
    ->numbers('919876543210')
    ->send();

Send SMS to Multiple Recipients:

$response = Msg91::sms()
    ->template('YOUR_TEMPLATE_ID')
    ->numbers(['919876543210', '919876543211'])
    ->variables(['number' => '3', 'date' => '22-12-2025'])
    ->send();

Send DLT SMS (Promotional):

$response = Msg91::sms()
    ->promotional()
    ->sender_id('YOUR_SENDER_ID')
    ->mobiles("9876543210,9876543211")
    ->dlt_template_id("YOUR_DLT_TEMPLATE_ID")
    ->message("Your promotional message here")
    ->send();

Send DLT SMS (Transactional):

$response = Msg91::sms()
    ->transactional()
    ->sender_id('YOUR_SENDER_ID')
    ->mobiles("9876543210")
    ->dlt_template_id("YOUR_DLT_TEMPLATE_ID")
    ->message("Your transactional message here")
    ->send();

OTP Examples

Send OTP (Template ID required for India):

$response = Msg91::otp()
    ->template('YOUR_OTP_TEMPLATE_ID')
    ->number('919876543210')
    ->send();

Send OTP with Custom Options:

$response = Msg91::otp()
    ->template('YOUR_OTP_TEMPLATE_ID')
    ->number('919876543210')
    ->length(6)        // OTP length (optional)
    ->expiry(10)      // Expiry in minutes (optional)
    ->send();

Verify OTP:

$response = Msg91::otp('123456')
    ->number('919876543210')
    ->verify();

Retry/Resend OTP:

// Retry as text SMS
$response = Msg91::otp()
    ->number('919876543210')
    ->viaText()
    ->retry();

// Retry as voice call
$response = Msg91::otp()
    ->number('919876543210')
    ->viaVoice()
    ->retry();

DLT Compliance for India

DLT (Distributed Ledger Technology) is mandatory for sending commercial SMS in India. TRAI requires all SMS messages to be DLT-compliant.

For Indian mobile numbers (country code 91), a Template ID is mandatory when sending OTP due to DLT compliance requirements. The package will automatically validate this requirement.

// ✅ Correct - Template ID provided for India
$response = Msg91::otp()
    ->template('YOUR_DLT_TEMPLATE_ID')  // Required for India
    ->number('919876543210')  // Indian number (starts with 91)
    ->send();

// ❌ Will throw error - Template ID missing for Indian number
$response = Msg91::otp()
    ->number('919876543210')  // Indian number
    ->send();  // Missing template() - will throw InvalidArgumentException

Error Handling

The package provides custom exception classes for better error handling:

use Kaydee123\Msg91\Exceptions\Msg91Exception;
use Kaydee123\Msg91\Exceptions\ApiException;

try {
    $response = Msg91::sms()
        ->template('YOUR_TEMPLATE_ID')
        ->numbers('919876543210')
        ->send();
} catch (ApiException $e) {
    // API-specific errors
    echo "API Error: " . $e->getMessage();
    echo "Status Code: " . $e->getStatusCode();
    print_r($e->getResponse());
} catch (Msg91Exception $e) {
    // General MSG91 errors
    echo "Error: " . $e->getMessage();
} catch (\Exception $e) {
    // Other errors
    echo "Unexpected error: " . $e->getMessage();
}

Configuration Options

The configuration file (config/msg91.php) supports the following options:

• auth_key - Your MSG91 authentication key (required)
• base_url - Base URL for MSG91 API (default: https://control.msg91.com/api/)
• timeout - Request timeout in seconds (default: 30)
• debug - Enable debug logging (default: false)

API Reference

For complete API documentation, refer to the base package documentation: kaydee123/msg91-php

SMSBuilder Methods

• template($templateId) - Set template ID for template-based SMS (required)
• numbers($mobiles) - Set recipient mobile number(s) - string or array
• to($mobile) - Set recipient mobile number(s) - string or array
• variables(array $variables) - Set multiple template variables (optional)
• variable($key, $value) - Set a single template variable (optional)
• recipients(array $recipients) - Set recipients with individual variables
• promotional() - Set route to promotional (route 1)
• transactional() - Set route to transactional (route 4, default)
• sender_id($id) - Set sender ID (required for DLT SMS)
• mobiles($mobiles) - Set mobiles for DLT SMS
• dlt_template_id($id) - Set DLT Template ID (India only)
• message($message) - Set SMS message content (required for DLT SMS)
• send() - Send the SMS

OTPBuilder Methods

• template($templateId) - Set template ID (required)
• number($mobile) - Set mobile number
• to($mobile) - Set mobile number
• length($digits) - Set OTP length/digits (optional, default: 4)
• expiry($minutes) - Set OTP expiry in minutes (optional, default: 1)
• viaText() - Set retry type to text
• viaVoice() - Set retry type to voice
• send() - Send OTP
• verify($otp) - Verify OTP code
• retry() - Retry/resend OTP
• resend() - Resend OTP (text by default)

Laravel Version Compatibility

This package is tested and compatible with:

• Laravel 8.x
• Laravel 9.x
• Laravel 10.x
• Laravel 11.x
• Laravel 12.x

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Support

For MSG91 API documentation, visit https://docs.msg91.com/

For issues related to this package, please open an issue on GitHub.

Related Packages

• kaydee123/msg91-php - The base PHP package (framework-agnostic)