A multi-channel messaging package for Laravel supporting SMS (via AfrikSMS) and WhatsApp (via Twilio). Features a fluent API, OTP verification, Laravel Notifications integration, and extensible gateway system.
- PHP 8.4+
- Laravel 11.x or 12.x
Install the package via Composer:
composer require ratoufa/laravel-messagingPublish the configuration file:
php artisan vendor:publish --tag="messaging-config"Add the following environment variables to your .env file:
# Default channel (sms or whatsapp)
MESSAGING_DEFAULT_CHANNEL=sms
# AfrikSMS credentials
AFRIKSMS_CLIENT_ID=your-client-id
AFRIKSMS_API_KEY=your-api-key
AFRIKSMS_SENDER_ID=MyApp
# Twilio WhatsApp credentials
TWILIO_SID=your-account-sid
TWILIO_AUTH_TOKEN=your-auth-token
TWILIO_WHATSAPP_FROM=whatsapp:+15551234567
# OTP settings (optional)
MESSAGING_OTP_LENGTH=6
MESSAGING_OTP_EXPIRY=10
MESSAGING_OTP_MAX_ATTEMPTS=3
# Phone formatting (optional)
MESSAGING_DEFAULT_COUNTRY_CODE=228use Ratoufa\Messaging\Facades\Sms;
// Fluent API
$response = Sms::to('22890123456')->send('Hello World!');
// With custom sender ID
$response = Sms::to('22890123456')
->from('MyBrand')
->send('Hello World!');
// Using a message object
use Ratoufa\Messaging\Data\SmsMessage;
$message = new SmsMessage(
recipient: '22890123456',
content: 'Hello World!',
senderId: 'MyBrand',
);
$response = Sms::send($message);use Ratoufa\Messaging\Facades\Sms;
// Fluent API - same message to multiple recipients
$response = Sms::toMany(['22890123456', '22891234567'])
->send('Bulk message to all');
// Using a message object
use Ratoufa\Messaging\Data\BulkMessage;
$message = new BulkMessage(
recipients: ['22890123456', '22891234567'],
content: 'Bulk message to all',
senderId: 'MyBrand',
);
$response = Sms::sendBulk($message);use Ratoufa\Messaging\Facades\Sms;
use Ratoufa\Messaging\Data\PersonalizedMessage;
$messages = [
new PersonalizedMessage('22890123456', 'Hello John, your code is 1234'),
new PersonalizedMessage('22891234567', 'Hello Jane, your code is 5678'),
];
$response = Sms::sendPersonalized($messages);use Ratoufa\Messaging\Facades\Sms;
$balances = Sms::getBalance();
foreach ($balances as $balance) {
echo "{$balance->country}: {$balance->balance} credits";
}use Ratoufa\Messaging\Facades\Sms;
// POST callback (default)
$response = Sms::configureCallback('https://example.com/webhook/sms');
// GET callback
$response = Sms::configureCallback('https://example.com/webhook/sms', 'GET');use Ratoufa\Messaging\Facades\WhatsApp;
// Simple message
$response = WhatsApp::to('22890123456')->send('Hello via WhatsApp!');
// Using a message object
use Ratoufa\Messaging\Data\SmsMessage;
$message = new SmsMessage(
recipient: '22890123456',
content: 'Hello via WhatsApp!',
);
$response = WhatsApp::send($message);use Ratoufa\Messaging\Facades\WhatsApp;
$response = WhatsApp::sendTemplate(
recipient: '22890123456',
contentSid: 'HXb5a34a7e18eb123456789',
variables: ['1' => 'John', '2' => 'Order #12345'],
);use Ratoufa\Messaging\Facades\WhatsApp;
// Image with caption
$response = WhatsApp::sendMedia(
recipient: '22890123456',
mediaUrl: 'https://example.com/image.jpg',
caption: 'Check this out!',
);
// Document without caption
$response = WhatsApp::sendMedia(
recipient: '22890123456',
mediaUrl: 'https://example.com/document.pdf',
);Note: WhatsApp has a 24-hour messaging window. You can send freeform messages only within 24 hours after the user's last reply. After that, you must use a pre-approved Message Template.
use Ratoufa\Messaging\Facades\WhatsApp;
// Fluent template with variables
$response = WhatsApp::to('22890123456')
->template('HXb5a34a7e18eb123456789', ['1' => 'John', '2' => 'Order #12345'])
->send();
// Template without variables
$response = WhatsApp::to('22890123456')
->template('HXb5a34a7e18eb123456789')
->send();
// Fluent media with caption
$response = WhatsApp::to('22890123456')
->media('https://example.com/image.jpg')
->send('Check this out!');use Ratoufa\Messaging\Facades\Otp;
$result = Otp::send('22890123456');
if ($result->success) {
echo "OTP sent, expires at: {$result->expiresAt}";
}
// With custom purpose
$result = Otp::send('22890123456', 'password-reset');use Ratoufa\Messaging\Facades\Otp;
$isValid = Otp::verify('22890123456', '123456');
if ($isValid) {
echo "OTP verified successfully!";
}
// With custom purpose
$isValid = Otp::verify('22890123456', '123456', 'password-reset');use Ratoufa\Messaging\Facades\Otp;
$result = Otp::resend('22890123456');use Ratoufa\Messaging\Facades\Otp;
$attempts = Otp::remainingAttempts('22890123456');
echo "Remaining attempts: {$attempts}";use Ratoufa\Messaging\Facades\Otp;
Otp::invalidate('22890123456');Note: WhatsApp OTP uses a pre-approved Message Template to ensure delivery even outside the 24-hour messaging window. You must configure the template SID in your
.envfile.
TWILIO_OTP_TEMPLATE_SID=HXxxxxxxxxxxxxxxxxx
TWILIO_OTP_CODE_VARIABLE=1use Ratoufa\Messaging\Facades\Otp;
// Send OTP via WhatsApp (uses template)
$result = Otp::whatsapp()->send('22890123456');
// Verify OTP (same as SMS)
$isValid = Otp::whatsapp()->verify('22890123456', '123456');
// Resend OTP via WhatsApp
$result = Otp::whatsapp()->resend('22890123456');The Messaging facade provides access to all channels:
use Ratoufa\Messaging\Facades\Messaging;
// SMS
Messaging::sms()->to('22890123456')->send('Hello!');
// WhatsApp
Messaging::whatsapp()->to('22890123456')->send('Hello!');
// OTP
Messaging::otp()->send('22890123456');
// Dynamic channel selection
Messaging::channel('sms')->to('22890123456')->send('Hello!');All send operations return a Response object:
use Ratoufa\Messaging\Facades\Sms;
use Ratoufa\Messaging\Enums\ResponseCode;
$response = Sms::to('22890123456')->send('Hello!');
// Check success
if ($response->success) {
echo "Message sent! ID: {$response->resourceId}";
}
// Check specific error codes
if ($response->code === ResponseCode::INSUFFICIENT_BALANCE) {
echo "Please recharge your account";
}
// Available response codes
ResponseCode::SUCCESS // 100
ResponseCode::INVALID_CREDENTIALS // 401
ResponseCode::INSUFFICIENT_BALANCE // 402
ResponseCode::INVALID_RECIPIENT // 422
ResponseCode::TEMPLATE_REQUIRED // 463 (WhatsApp 24h window expired)
ResponseCode::SERVER_ERROR // 500use Illuminate\Notifications\Notification;
use Ratoufa\Messaging\Data\SmsMessage;
class OrderShipped extends Notification
{
public function via($notifiable): array
{
return ['sms'];
}
public function toSms($notifiable): SmsMessage
{
return new SmsMessage(
recipient: $notifiable->phone,
content: "Your order #{$this->order->id} has been shipped!",
);
}
}use Illuminate\Notifications\Notification;
use Ratoufa\Messaging\Data\SmsMessage;
class OrderShipped extends Notification
{
public function via($notifiable): array
{
return ['whatsapp'];
}
public function toWhatsApp($notifiable): SmsMessage
{
return new SmsMessage(
recipient: $notifiable->phone,
content: "Your order #{$this->order->id} has been shipped!",
);
}
}Add the HasMessaging trait to your model for quick messaging:
use Ratoufa\Messaging\Concerns\HasMessaging;
class User extends Authenticatable
{
use HasMessaging;
// Define the phone field (defaults to 'phone')
public function routeNotificationForSms(): ?string
{
return $this->phone_number;
}
public function routeNotificationForWhatsApp(): ?string
{
return $this->whatsapp_number;
}
}Usage:
$user->sendSms('Hello!');
$user->sendWhatsApp('Hello via WhatsApp!');
$user->sendOtp();
$user->verifyOtp('123456');You can register custom gateways:
use Ratoufa\Messaging\Contracts\GatewayInterface;
use Ratoufa\Messaging\Facades\Messaging;
class MyCustomGateway implements GatewayInterface
{
public function send(SmsMessage $message): Response
{
// Your implementation
}
public function getBalance(): Collection
{
// Your implementation
}
}
// Register the gateway
Messaging::extend('custom', new MyCustomGateway());
// Use it
Messaging::channel('custom')->to('22890123456')->send('Hello!');Check your account balance:
php artisan messaging balance
php artisan messaging balance --channel=whatsappThe package includes a phone formatter utility:
use Ratoufa\Messaging\Support\PhoneFormatter;
$formatter = new PhoneFormatter();
// Format with default country code (from config)
$phone = $formatter->format('90123456'); // "22890123456"
// Format with specific country code
$phone = $formatter->format('90123456', '229'); // "22990123456"
// Format for WhatsApp
$phone = $formatter->formatForWhatsApp('22890123456'); // "whatsapp:+22890123456"
// Format multiple numbers
$phones = $formatter->formatMany(['90123456', '91234567']);
// Validate phone number
$isValid = $formatter->isValid('22890123456'); // trueThe package dispatches events for delivery reports:
use Ratoufa\Messaging\Events\MessageDeliveryReportReceived;
class MessageDeliveryListener
{
public function handle(MessageDeliveryReportReceived $event): void
{
$messageId = $event->messageId;
$status = $event->status; // DeliveryStatus enum
$recipient = $event->recipient;
$deliveredAt = $event->deliveredAt;
}
}Register in EventServiceProvider:
protected $listen = [
MessageDeliveryReportReceived::class => [
MessageDeliveryListener::class,
],
];composer testThis runs:
- PHPStan (static analysis)
- Pest (unit & feature tests)
- Pint (code style)
- Rector (refactoring checks)
- Peck (typo detection)
Please see CHANGELOG for more information on what has changed recently.
Please see CONTRIBUTING for details.
Please review our security policy on how to report security vulnerabilities.
The MIT License (MIT). Please see License File for more information.