Installation

composer require aghfatehi/laravel-msegat

Laravel auto-discovery registers the service provider and facade automatically.

Publish Configuration

php artisan vendor:publish --provider="Aghfatehi\Msegat\MsegatServiceProvider" --tag=msegat-config

Publish Migrations (Optional)

Track sent messages, OTP requests, delivery reports, and webhooks in your database. If you publish and run the migrations, five tables will be created:

This step is optional. The package works fully without migrations — skip this section if you don't need database logging.

Option A — Run migrations directly from the package (recommended):

Runs only the package's migrations without publishing:

php artisan migrate --path=/vendor/aghfatehi/laravel-msegat/database/migrations

Option B — Publish then migrate (if you need to modify the migrations):

php artisan vendor:publish --provider="Aghfatehi\Msegat\MsegatServiceProvider" --tag=msegat-migrations
php artisan migrate

Configuration

Add to your .env (required variables marked with REQUIRED):

# ─── REQUIRED ───────────────────────────────────────
MSEGAT_USERNAME=your_username
MSEGAT_API_KEY=your_api_key

# ─── OPTIONAL ───────────────────────────────────────
MSEGAT_SENDER=YourSender
MSEGAT_BASE_URL=https://www.msegat.com/gw/
MSEGAT_TIMEOUT=30
MSEGAT_RETRIES=3
MSEGAT_VERIFY_SSL=true
MSEGAT_QUEUE_ENABLED=false
MSEGAT_LOGGING_ENABLED=true
MSEGAT_WEBHOOK_SECRET=your_webhook_secret
MSEGAT_WHATSAPP_EMAIL=your_t2_email
MSEGAT_WHATSAPP_PASSWORD=your_t2_password

Config Options

Usage

SMS

use Aghfatehi\Msegat\Facades\Msegat;

// Single recipient
$response = Msegat::sms()
    ->to('966512345678')
    ->message('Hello World')
    ->send();

// Multiple recipients
$response = Msegat::sms()
    ->to(['966512345678', '966598765432'])
    ->message('Bulk message')
    ->send();

// Custom sender
$response = Msegat::sms()
    ->sender('CustomAD')
    ->to('966512345678')
    ->message('Custom sender test')
    ->send();

// Scheduled message
$response = Msegat::sms()
    ->to('966512345678')
    ->message('Scheduled message')
    ->at('2026-12-01 10:00:00')
    ->send();

// Get bulk ID
$response = Msegat::sms()
    ->to(['966512345678', '966598765432'])
    ->message('Get bulk ID')
    ->options(['reqBulkId' => true])
    ->send();

$bulkId = $response->bulkId;

Personalized Messages

$response = Msegat::sms()
    ->to(['966512345678', '966598765432'])
    ->message('Hello {name}, your order {order} is ready')
    ->sendPersonalized([
        ['name' => 'Ahmed', 'order' => '1001'],
        ['name' => 'Mohammed', 'order' => '1002'],
    ]);

OTP

// Send OTP
$otpResponse = Msegat::otp()
    ->to('966512345678')
    ->sendOtp();

$otpId = $otpResponse->otpId;

// Verify OTP
$verification = Msegat::otp()
    ->to('966512345678')
    ->verifyOtp('123456');

if ($verification->successful) {
    // OTP verified
}

WhatsApp (T2 Communicate API)

WhatsApp messages are sent via the T2 Communicate WhatsApp Business API — a separate gateway from Msegat SMS. Requires its own credentials.

Text Message

$response = Msegat::whatsapp()
    ->to('966512345678')
    ->message('Hello from WhatsApp!')
    ->send();

$messageId = $response->messageId;

Template Message

$response = Msegat::whatsapp()
    ->to('966512345678')
    ->template('welcome')
    ->variables(['John', 'Support'])
    ->send();

if ($response->successful) {
    echo "Sent: {$response->messageId}";
}

Response Object

Balance

$balance = Msegat::getBalance();
$credits = $balance->balance; // float

Message Cost Calculation

$cost = Msegat::sms()
    ->to(['966512345678', '966598765432'])
    ->message('Test message')
    ->calculateCost();
// Returns float

Sender Management

// List senders
$senders = Msegat::getSenders();

// Add sender
// (available via direct API call - endpoint: addSender.php)

Retrieve Messages

$messages = Msegat::forBulkId('BULK123')
    ->getMessages();

$messages = Msegat::forBulkId('BULK123')
    ->page(2)
    ->limit(10)
    ->getMessages();

Test Message

Msegat::sms()
    ->to('966512345678')
    ->sendTestMessage();

Queue Support

// Dispatch to default queue
Msegat::sms()
    ->to('966512345678')
    ->message('Queued message')
    ->queue();

// Custom queue connection
Msegat::sms()
    ->to('966512345678')
    ->message('Queued message')
    ->queue('redis', 'high');

The SendSmsJob retries up to 3 times with a 5-second backoff.

Events

Example listener registration in EventServiceProvider:

protected $listen = [
    \Aghfatehi\Msegat\Events\MessageSent::class => [
        \App\Listeners\LogMsegatMessage::class,
    ],
];

Webhooks

The package registers four webhook routes under the /webhook/msegat/ prefix:

Signature Verification

Set MSEGAT_WEBHOOK_SECRET in .env and each webhook request must include:

• X-Msegat-Signature: HMAC-SHA256 of timestamp.payload
• X-Msegat-Timestamp: Unix timestamp

Requests outside a 5-minute tolerance window are rejected.

Notification Channel

namespace App\Notifications;

use Illuminate\Notifications\Notification;

class WelcomeSms extends Notification
{
    public function via($notifiable): array
    {
        return ['msegat'];
    }

    public function toMsegat($notifiable): string
    {
        return "Welcome {$notifiable->name} to our platform!";
    }
}

Add routeNotificationForMsegat() to your notifiable model:

public function routeNotificationForMsegat(): string
{
    return $this->phone;
}

Artisan Commands

# Check account balance
php artisan msegat:balance

# List registered senders
php artisan msegat:senders

Testing

composer test

With coverage:

composer test-coverage

The test suite includes:

• Unit Tests: DTOs, enums, exceptions, phone formatter, WhatsApp response
• Feature Tests: SMS sending, OTP, balance, webhooks, config, WhatsApp text/template
• Integration Tests: Events, queues

Code Quality (For Contributors)

# Laravel Pint (PSR-12)
composer lint

# Auto-fix
composer lint-fix

# PHPStan (level 6)
composer analyse

# Rector
composer rector

Database Migrations

Status Codes and Messages

Success

Errors

Changelog

See CHANGELOG for recent changes.

Security

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

Contributing

Contributions are welcome! Please follow these steps to contribute:

1. Fork the repository.
2. Create a new branch (git checkout -b feature/new-feature).
3. Commit your changes (git commit -am 'Add new feature').
4. Push to the branch (git push origin feature/new-feature).
5. Create a new Pull Request.

Support

If you have any questions or issues, feel free to open an issue on the GitHub repository or contact the author AL-AGHBARI Fatehi.

License

The MIT License (MIT). See LICENSE for details.