README

A Laravel package for integrating with the VaraSMS messaging service. This package provides an easy way to send SMS messages, manage customer balances, and interact with the VaraSMS API.

Installation

You can install the package via composer:

composer require varaai/varasms

Configuration

Publish the configuration file:

php artisan vendor:publish --provider="VaraSMS\Laravel\VaraSMSServiceProvider"

Add the following environment variables to your .env file:

For username/password authentication (default):

VARASMS_AUTH_METHOD=basic
VARASMS_USERNAME=your_username
VARASMS_PASSWORD=your_password
VARASMS_SENDER_ID=your_sender_id
VARASMS_BASE_URL=https://messaging-service.co.tz
VARASMS_TEST_MODE=false  # Set to true to use test endpoints

Or for token-based authentication:

VARASMS_AUTH_METHOD=token
VARASMS_TOKEN=your_authorization_token
VARASMS_SENDER_ID=your_sender_id
VARASMS_BASE_URL=https://messaging-service.co.tz
VARASMS_TEST_MODE=false  # Set to true to use test endpoints

Test Mode

When VARASMS_TEST_MODE is set to true, all API calls will be directed to the test endpoints. This is useful for development and testing without sending actual SMS messages.

Example test mode configuration:

VARASMS_TEST_MODE=true

Usage

Send a Single SMS

use VaraSMS\Laravel\Facades\VaraSMS;

// Send to a single recipient
$response = VaraSMS::sendSMS('255738234345', 'Hello World!');

// Send with custom sender ID and reference
$response = VaraSMS::sendSMS(
    '255738234345',
    'Hello World!',
    'MYSENDER',
    'ref123'
);

// Send to multiple recipients
$response = VaraSMS::sendSMS(
    [
        '255738234345',
        '255716718040'
    ],
    'Hello everyone!',
    'MYSENDER',
    'ref123'
);

The sendSMS method supports both single and multiple recipients:

Send SMS Response

// Single recipient response
[
    'success' => true,
    'message' => 'Message sent successfully',
    'data' => [
        'message_id' => '123456',
        'to' => '255738234345',
        'status' => 'SENT',
        'reference' => 'ref123'
    ]
]

// Multiple recipients response
[
    'success' => true,
    'message' => 'Messages sent successfully',
    'data' => [
        [
            'message_id' => '123456',
            'to' => '255738234345',
            'status' => 'SENT',
            'reference' => 'ref123'
        ],
        [
            'message_id' => '123457',
            'to' => '255716718040',
            'status' => 'SENT',
            'reference' => 'ref123'
        ]
    ]
]

Send Bulk SMS

use VaraSMS\Laravel\Facades\VaraSMS;

$messages = [
    [
        'to' => '255738234345',
        'message' => 'Hello User 1!',
        'reference' => 'ref1'
    ],
    [
        'to' => '255738234346',
        'message' => 'Hello User 2!',
        'reference' => 'ref2'
    ]
];

$response = VaraSMS::sendBulkSMS($messages);

Get Delivery Reports

use VaraSMS\Laravel\Facades\VaraSMS;

// Get all delivery reports
$reports = VaraSMS::getDeliveryReports();

// Get delivery report for a specific message ID
$report = VaraSMS::getDeliveryReport('28089492984101631440');

// Get delivery reports by date range (Deprecated)
$reports = VaraSMS::getDeliveryReportsByDateRange('2024-03-01', '2024-03-15');

Check Balance

use VaraSMS\Laravel\Facades\VaraSMS;

$balance = VaraSMS::getBalance();

Recharge Customer

use VaraSMS\Laravel\Facades\VaraSMS;

$response = VaraSMS::rechargeCustomer('customer@example.com', 5000);

Deduct Customer Balance

use VaraSMS\Laravel\Facades\VaraSMS;

$response = VaraSMS::deductCustomer('customer@example.com', 2000);

Get SMS Logs

use VaraSMS\Laravel\Facades\VaraSMS;

// Get all SMS logs
$logs = VaraSMS::getSMSLogs();

// Get SMS logs with filters
$logs = VaraSMS::getSMSLogs([
    'from' => 'NEXTSMS',          // Filter by sender ID
    'to' => '255716718040',       // Filter by recipient number
    'sentSince' => '2024-03-01',  // Filter messages sent from this date
    'sentUntil' => '2024-03-15',  // Filter messages sent until this date
    'limit' => 500,               // Limit number of records (max 500)
    'offset' => 20,               // Skip first 20 records
    'reference' => 'ref123'       // Filter by message reference
]);

The getSMSLogs method supports the following filters:

All filters are optional. You can use any combination of filters to narrow down your search.

SMS Logs Response

[
    'success' => true,
    'logs' => [
        [
            'message_id' => '123456',
            'sender' => 'NEXTSMS',
            'recipient' => '255738234345',
            'message' => 'Hello World!',
            'status' => 'SENT',
            'timestamp' => '2024-03-24 10:30:00',
            'reference' => 'ref123'
        ],
        // ... more logs
    ],
    'pagination' => [
        'total' => 100,
        'offset' => 20,
        'limit' => 500
    ]
]

Register Sub-Customer (Resellers Only)

use VaraSMS\Laravel\Facades\VaraSMS;

$response = VaraSMS::registerSubCustomer([
    'first_name' => 'Api',
    'last_name' => 'Customer',
    'username' => 'apicust',
    'email' => 'apicust@customer.com',
    'phone_number' => '0738234339',  // Can be in format 0XXXXXXXXX or 255XXXXXXXXX
    'account_type' => 'Sub Customer (Reseller)', // or 'Sub Customer'
    'sms_price' => 20
]);

The registerSubCustomer method requires the following parameters:

Sub-Customer Registration Response

[
    'success' => true,
    'message' => 'Sub-customer registered successfully',
    'data' => [
        'id' => 123,
        'first_name' => 'Api',
        'last_name' => 'Customer',
        'username' => 'apicust',
        'email' => 'apicust@customer.com',
        'phone_number' => '255738234339',
        'account_type' => 'Sub Customer (Reseller)',
        'sms_price' => 20,
        'created_at' => '2024-03-24 10:30:00'
    ]
]

Note: This feature is only available for customers in the reseller program.

Response Format

All methods return an array containing the API response. Here are some example responses:

Send SMS Response

[
    'success' => true,
    'message' => 'Message sent successfully',
    'reference' => 'ref123'
]

Delivery Reports Response

[
    'success' => true,
    'reports' => [
        [
            'message_id' => '123456',
            'status' => 'DELIVERED',
            'recipient' => '255738234345',
            'timestamp' => '2024-03-24 10:30:00'
        ],
        // ... more reports
    ]
]

Balance Response

[
    'sms_balance' => 5000
]

Recharge/Deduct Response

[
    'success' => true,
    'status' => 200,
    'message' => 'Transaction completed successfully',
    'result' => [
        'Customer' => 'customer@example.com',
        'Sms transferred' => 5000,
        'Your sms balance' => 450000
    ]
]

Error Handling

The package throws exceptions when API calls fail. It's recommended to wrap API calls in try-catch blocks:

try {
    $response = VaraSMS::sendSMS('255738234345', 'Hello World!');
} catch (\Exception $e) {
    // Handle the error
    Log::error('SMS sending failed: ' . $e->getMessage());
}

Testing

The package includes comprehensive tests. To run the tests:

composer test

To generate test coverage reports:

composer test-coverage

Test Environment

For testing your application with VaraSMS, you can use the test mode by setting your base URL to the test endpoint:

VARASMS_BASE_URL=https://messaging-service.co.tz/api/sms/v1/test

Writing Tests

When writing tests for your application that uses VaraSMS, you can mock the VaraSMS facade:

use VaraSMS\Laravel\Facades\VaraSMS;

class YourTest extends TestCase
{
    public function test_sends_sms()
    {
        VaraSMS::shouldReceive('sendSMS')
            ->once()
            ->with('255738234345', 'Test message')
            ->andReturn([
                'success' => true,
                'message' => 'Message sent successfully'
            ]);

        // Your test code here
    }
}

License

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

Schedule SMS Messages

use VaraSMS\Laravel\Facades\VaraSMS;

// Schedule a one-time SMS
$response = VaraSMS::scheduleSMS(
    '255716718040',
    'Your message',
    '2024-03-25',  // Date in Y-m-d format
    '14:30',       // Time in 24-hour format
    'NEXTSMS'      // Optional sender ID
);

// Schedule a recurring SMS
$response = VaraSMS::scheduleSMS(
    '255716718040',
    'Your recurring message',
    '2024-03-25',  // Initial send date
    '14:30',       // Time to send
    'NEXTSMS',     // Optional sender ID
    [
        'repeat' => 'daily',           // hourly, daily, weekly, or monthly
        'start_date' => '2024-03-25',  // Optional start date for recurring
        'end_date' => '2024-04-25'     // Optional end date for recurring
    ]
);

The scheduleSMS method supports both one-time and recurring message scheduling:

Required Parameters:

Optional Parameters:

Recurring Settings:

Schedule SMS Response

[
    'success' => true,
    'message' => 'Message scheduled successfully',
    'data' => [
        'message_id' => '123456',
        'to' => '255716718040',
        'schedule_time' => '2024-03-25 14:30:00',
        'repeat' => 'daily',           // Only for recurring messages
        'start_date' => '2024-03-25',  // Only for recurring messages
        'end_date' => '2024-04-25'     // Only for recurring messages
    ]
]

Send Multiple Different Messages

use VaraSMS\Laravel\Facades\VaraSMS;

// Send different messages to different groups of recipients
$response = VaraSMS::sendMultipleMessages([
    [
        'to' => [
            '255716718040',
            '255758483019'
        ],
        'text' => 'First message to group 1',
        'from' => 'NEXTSMS'  // Optional sender ID
    ],
    [
        'to' => [
            '255758483019',
            '255655912841',
            '255716718040'
        ],
        'text' => 'Second message to group 2'
        // Using default sender ID from config
    ]
], 'batch123');  // Optional global reference

The sendMultipleMessages method allows you to send different messages to different groups of recipients in a single API call:

Each message in the messages array should have:

• to: Single phone number or array of numbers (must start with 255)
• text: The message content
• from: Optional sender ID (uses default if not provided)

Multiple Messages Response

[
    'success' => true,
    'message' => 'Messages sent successfully',
    'data' => [
        [
            'message_id' => '123456',
            'to' => ['255716718040', '255758483019'],
            'status' => 'SENT',
            'text' => 'First message to group 1'
        ],
        [
            'message_id' => '123457',
            'to' => ['255758483019', '255655912841', '255716718040'],
            'status' => 'SENT',
            'text' => 'Second message to group 2'
        ]
    ],
    'reference' => 'batch123'
]