README

A modern, fluent, feature-complete PHP SDK and Laravel Package for the Zender Messaging Platform (SMS, WhatsApp, OTP, USSD, Gateway Devices & Contacts management).

Features

⚡ Full API Coverage: 100% support for all 54 Zender REST API endpoints.
📱 SMS Integration: Single SMS, Bulk SMS, SMS Campaigns (Start/Stop), Sent/Received/Pending message logs.
💬 WhatsApp Integration: Text chats, Media attachments (Images, Audio, Video), Documents (PDF, XML, DOC, XLSX), Group Messaging, WhatsApp Number Validation, Linked Accounts & QR status.
🔐 OTP Engine: Send auto-expiring OTP codes via SMS or WhatsApp and verify them with a single call.
📞 USSD Automation: Send USSD codes and inspect response logs.
📇 Contacts & Groups: Manage contact books, groups, and unsubscribed contact lists.
🤖 Android Gateways: Fetch gateway devices, manage notifications.
🚀 Laravel Ready: Auto-discovery, configuration publishing, container binding, and fluent Facade syntax (Zender::sms()->send(...)).
🛠️ Pure PHP Supported: Works seamlessly in standard PHP applications without framework dependencies.

Requirements

PHP ^8.1 or higher
guzzlehttp/guzzle: ^7.5
For Laravel integration: Laravel ^9.0, ^10.0, ^11.0, or ^12.0

Installation

Install the package via Composer:

composer require limon/laravel-zender

Laravel Setup

1. Configuration

If using Laravel, the service provider and facade will be automatically registered via Package Auto-Discovery.

Publish the configuration file using:

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

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

2. Environment Variables

Add your Zender Site URL and API Secret (copied from your Zender Dashboard under Tools -> API Keys) to your .env file:

ZENDER_SITE_URL=https://sms.yourdomain.com/
ZENDER_API_SECRET=your_api_secret_here
ZENDER_TIMEOUT=30
ZENDER_VERIFY_SSL=true

Laravel Usage Examples

1. Send SMS Messages

use Zender\Laravel\Facades\Zender;

// Send Single SMS via Gateway Device
$response = Zender::sms()->send([
    'mode' => 'devices',
    'phone' => '+1234567890',
    'message' => 'Hello! {Your order #1001 is now shipped.|Thank you for your purchase!}',
    'device' => 'DEVICE_UNIQUE_ID',
    'sim' => 1,
    'priority' => 1, // 1 = Immediate, 2 = Queued
]);

// Send Bulk SMS
$response = Zender::sms()->sendBulk([
    'mode' => 'gateways',
    'campaign' => 'Summer Discount Campaign',
    'message' => 'Special offer for you!',
    'numbers' => '+1234567890,+9876543210',
    'gateway' => 5,
]);

2. Send WhatsApp Messages & Attachments

// Send WhatsApp Text Message
$response = Zender::whatsapp()->send([
    'account' => 'WA_ACCOUNT_UNIQUE_ID',
    'recipient' => '+1234567890',
    'message' => 'Hello via WhatsApp!',
]);

// Send WhatsApp Image/Media via Direct URL
$response = Zender::whatsapp()->send([
    'account' => 'WA_ACCOUNT_UNIQUE_ID',
    'recipient' => '+1234567890',
    'type' => 'media',
    'message' => 'Check out our new catalog!',
    'media_url' => 'https://example.com/catalog.jpg',
    'media_type' => 'image', // image, audio, or video
]);

// Send WhatsApp PDF Document from local file
$response = Zender::whatsapp()->send([
    'account' => 'WA_ACCOUNT_UNIQUE_ID',
    'recipient' => '+1234567890',
    'type' => 'document',
    'message' => 'Attached invoice',
    'document_file' => storage_path('app/invoices/inv_1001.pdf'),
]);

// Validate if a number exists on WhatsApp
$validation = Zender::whatsapp()->validate('WA_ACCOUNT_UNIQUE_ID', '+1234567890');

3. Send & Verify OTP Codes

// Send OTP via SMS
$otp = Zender::otp()->send([
    'type' => 'sms',
    'phone' => '+1234567890',
    'message' => 'Your security code is {otp}. Valid for 5 minutes.',
    'expire' => 5,
    'mode' => 'devices',
    'device' => 'DEVICE_UNIQUE_ID',
]);

// Verify User Inputted OTP
$verification = Zender::otp()->verify('543210');

if ($verification['status'] === 200) {
    // OTP is valid!
}

4. Check Account Balance & Credits

$credits = Zender::account()->getCredits();
$subscription = Zender::account()->getSubscription();

Standalone PHP Usage

You can also use this package in pure PHP projects without Laravel:

require_once 'vendor/autoload.php';

use Zender\Zender;

$zender = new Zender([
    'site_url' => 'https://sms.yourdomain.com/',
    'api_secret' => 'your_api_secret_here',
    'timeout' => 30,
    'verify_ssl' => true,
]);

// Send SMS
$result = $zender->sms()->send([
    'mode' => 'devices',
    'phone' => '+1234567890',
    'message' => 'Hello from pure PHP!',
    'device' => 'DEVICE_UNIQUE_ID',
]);

Complete API Reference

Service Method	Description
`Zender::sms()`
`send(array $params)`	Send a single SMS message
`sendBulk(array $params)`	Send bulk SMS messages to numbers or groups
`getMessage(int $id, string $type)`	Get single SMS details (`type`: sent/received)
`getSent(int $limit, int $page)`	Fetch sent SMS logs
`getReceived(int $limit, int $page)`	Fetch received SMS logs
`getPending(int $limit, int $page)`	Fetch pending SMS queue
`getCampaigns(int $limit, int $page)`	List SMS campaigns
`deleteSent(int $id)`	Delete sent SMS log
`deleteReceived(int $id)`	Delete received SMS log
`deleteCampaign(int $id)`	Delete SMS campaign
`startCampaign(int $campaignId)`	Remote start an SMS campaign
`stopCampaign(int $campaignId)`	Remote stop an SMS campaign
`Zender::whatsapp()`
`send(array $params)`	Send WhatsApp text, media, or document message
`sendBulk(array $params)`	Send bulk WhatsApp chats
`getMessage(int $id, string $type)`	Fetch single WhatsApp message details
`getSent(int $limit, int $page)`	Fetch sent WhatsApp logs
`getReceived(int $limit, int $page)`	Fetch received WhatsApp logs
`getPending(int $limit, int $page)`	Fetch pending WhatsApp queue
`getCampaigns(int $limit, int $page)`	Fetch WhatsApp campaigns
`getAccounts(int $limit, int $page)`	Fetch connected WhatsApp accounts
`getGroups(string $uniqueId)`	List WhatsApp groups
`getGroupContacts(string $unique, string $gid)`	Get WhatsApp group contact list
`validate(string $unique, string $phone)`	Check if phone number exists on WhatsApp
`getQr(string $token)`	Get WhatsApp QR link token data
`getServers()`	List available WhatsApp servers
`createLink(string $sid)`	Link a new WhatsApp account
`relink(string $sid, string $unique)`	Relink existing WhatsApp account
`startCampaign(int $campaignId)`	Remote start WhatsApp campaign
`stopCampaign(int $campaignId)`	Remote stop WhatsApp campaign
`deleteSent(int $id)`	Delete sent WhatsApp log
`deleteReceived(int $id)`	Delete received WhatsApp log
`deleteAccount(string $unique)`	Unlink/delete WhatsApp account
`deleteCampaign(int $id)`	Delete WhatsApp campaign
`Zender::otp()`
`send(array $params)`	Dispatch OTP code via SMS or WhatsApp
`verify(string $otp)`	Verify OTP code
`Zender::contacts()`
`createContact(array $params)`	Add contact to phonebook
`createGroup(array $params)`	Create contact group
`getContacts(int $limit, int $page)`	Fetch contacts list
`getGroups(int $limit, int $page)`	Fetch groups list
`getUnsubscribed(int $limit, int $page)`	Fetch unsubscribed list
`deleteContact(int $id)`	Delete contact
`deleteGroup(int $id)`	Delete group
`deleteUnsubscribed(int $id)`	Delete unsubscribed entry
`Zender::ussd()`
`send(array $params)`	Send USSD request to device
`get(int $limit, int $page)`	Fetch USSD request logs
`delete(int $id)`	Delete USSD request log
`Zender::android()`
`getDevices(int $limit, int $page)`	Fetch connected Android gateway devices
`deleteNotification(int $id)`	Delete Android notification log
`Zender::account()`
`getCredits()`	Fetch remaining account credits
`getSubscription()`	Fetch active subscription package details
`getEarnings()`	Fetch partner earnings details
`Zender::gateway()`
`getRates()`	Fetch gateway rates list
`Zender::misc()`
`getShorteners()`	Fetch list of available URL shorteners

Exception Handling

The package throws Zender\Exceptions\ZenderApiException for HTTP errors or API status failures.

use Zender\Exceptions\ZenderApiException;
use Zender\Laravel\Facades\Zender;

try {
    $response = Zender::sms()->send([
        'mode' => 'devices',
        'phone' => '+1234567890',
        'message' => 'Hello!',
        'device' => 'INVALID_DEVICE_ID',
    ]);
} catch (ZenderApiException $e) {
    echo "API Error Code: " . $e->getStatusCode() . "\n";
    echo "Error Message: " . $e->getMessage() . "\n";
    print_r($e->getResponseBody());
}

Testing

Run unit tests using PHPUnit:

vendor/bin/phpunit

License

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

limon / laravel-zender

Maintainers

Package info

Statistics

Security