timothydake/nigeriabulksms-sdk

A production-grade PHP SDK for NigeriaBulkSMS API. Provides SMS sending, voice calls, audio uploads, and data fetching functionality with Laravel integration.

v1.0.1 2025-07-12 06:21 UTC

Requires

• php: >=7.4
• guzzlehttp/guzzle: ^7.0

MIT

• Timothy Dake

• api
• sms
• sdk
• laravel
• tts
• Nigeria
• bulk-sms
• voice-calls
• nigeriabulksms
• nigerian-bulk-sms
• nigerian-bulk-sms-api
• nigerian-bulk-sms-sdk
• nigerian-bulk-sms-laravel
• nigerian-bulk-sms-laravel-sdk
• nigerian-bulk-sms-laravel-api

README

A production-grade PHP SDK for the NigeriaBulkSMS.com API. This SDK provides a simple, robust, and type-safe way to integrate bulk SMS, voice messaging, and data fetching functionalities into your PHP and Laravel applications.

Features

• 🚀 Easy to use - Simple and intuitive API
• 🛡️ Robust error handling - Comprehensive error types and validation
• 📱 SMS & Voice - Support for text messages, voice calls, and TTS
• 📊 Data fetching - Access to account balance, history, and more
• 📦 Laravel Support - Seamless integration with Laravel applications

Installation

This SDK can be installed via Composer.

composer require your-vendor-name/nigeriabulksms-sdk

Replace your-vendor-name with your desired vendor name when publishing the package.

Basic Usage (PHP)

First, initialize the NigeriaBulkSMS client with your username and password.

<?php

require_once __DIR__ . "/vendor/autoload.php";

use NigeriaBulkSMS\NigeriaBulkSMS;
use NigeriaBulkSMS\Exception\NigeriaBulkSMSException;

$username = "YOUR_USERNAME";
$password = "YOUR_PASSWORD";

$client = new NigeriaBulkSMS($username, $password);

try {
    // Send an SMS
    $smsResponse = $client->sms()->send(
        "Hello from NigeriaBulkSMS PHP SDK!",
        "YourApp",
        "2348030000000"
    );
    echo "SMS sent successfully: " . json_encode($smsResponse) . "\n";

    // Get account balance
    $balanceResponse = $client->dataFetcher()->getBalance();
    echo "Account Balance: " . json_encode($balanceResponse) . "\n";

} catch (NigeriaBulkSMSException $e) {
    echo "Error: " . $e->getMessage() . " (Code: " . $e->getCode() . ")\n";
} catch (Exception $e) {
    echo "An unexpected error occurred: " . $e->getMessage() . "\n";
}

?>

Laravel Integration

1. Publish the Configuration File

After installing the package, publish the configuration file using the artisan command:

php artisan vendor:publish --provider="NigeriaBulkSMS\\Laravel\\NigeriaBulkSMSServiceProvider"

This will create a nigeriabulksms.php file in your config directory. You can then set your API credentials in your .env file:

NIGERIABULKSMS_USERNAME=your_username
NIGERIABULKSMS_PASSWORD=your_password

2. Usage in Laravel

You can use the NigeriaBulkSMS facade or inject the NigeriaBulkSMS class directly.

Using the Facade

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use NigeriaBulkSMS\Laravel\NigeriaBulkSMSFacade as NigeriaBulkSMS;
use NigeriaBulkSMS\Exception\NigeriaBulkSMSException;

class SMSController extends Controller
{
    public function sendSMS(Request $request)
    {
        try {
            $response = NigeriaBulkSMS::sms()->send(
                "Hello from Laravel!",
                "LaravelApp",
                "2348030000000"
            );
            return response()->json(["status" => "success", "data" => $response]);
        } catch (NigeriaBulkSMSException $e) {
            return response()->json(["status" => "error", "message" => $e->getMessage(), "code" => $e->getCode()], 500);
        } catch (Exception $e) {
            return response()->json(["status" => "error", "message" => "An unexpected error occurred: " . $e->getMessage()], 500);
        }
    }
}

Using Dependency Injection

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use NigeriaBulkSMS\NigeriaBulkSMS;
use NigeriaBulkSMS\Exception\NigeriaBulkSMSException;

class SMSController extends Controller
{
    protected $nigeriaBulkSMS;

    public function __construct(NigeriaBulkSMS $nigeriaBulkSMS)
    {
        $this->nigeriaBulkSMS = $nigeriaBulkSMS;
    }

    public function sendSMS(Request $request)
    {
        try {
            $response = $this->nigeriaBulkSMS->sms()->send(
                "Hello from Laravel with DI!",
                "LaravelDI",
                "2348030000000"
            );
            return response()->json(["status" => "success", "data" => $response]);
        } catch (NigeriaBulkSMSException $e) {
            return response()->json(["status" => "error", "message" => $e->getMessage(), "code" => $e->getCode()], 500);
        } catch (Exception $e) {
            return response()->json(["status" => "error", "message" => "An unexpected error occurred: " . $e->getMessage()], 500);
        }
    }
}

API Reference

NigeriaBulkSMS Client

The main client class to interact with the NigeriaBulkSMS API.

new NigeriaBulkSMS(string $username, string $password)

SMS Service

Access SMS functionalities via $client->sms().

send(string $message, string $sender, string|array $mobiles)

Sends a text message to one or more mobile numbers.

• $message (string): The content of the SMS message.
• $sender (string): The sender ID (max 11 alphanumeric characters).
• $mobiles (string|array): A single mobile number or an array of mobile numbers. Numbers should be in international format (e.g., 2348030000000).

$response = $client->sms()->send("Your message", "SenderID", "2348030000000");
// Or for multiple recipients:
$response = $client->sms()->send("Your message", "SenderID", ["2348030000000", "2348020000000"]);

Call Service

Access call functionalities via $client->call().

sendTTS(string $message, string $sender, string|array $mobiles)

Sends a Text-to-Speech (TTS) call to one or more mobile numbers.

• $message (string): The text to be converted to speech.
• $sender (string): The sender ID.
• $mobiles (string|array): A single mobile number or an array of mobile numbers.

$response = $client->call()->sendTTS("Hello, this is a test call.", "YourApp", "2348030000000");

sendAudio(string $audioReference, string $sender, string|array $mobiles)

Sends a pre-recorded audio call to one or more mobile numbers using an audio reference.

• $audioReference (string): The reference ID of the uploaded audio file.
• $sender (string): The sender ID.
• $mobiles (string|array): A single mobile number or an array of mobile numbers.

$response = $client->call()->sendAudio("your-audio-reference-id", "YourApp", "2348030000000");

Audio Service

Access audio functionalities via $client->audio().

upload(string $url)

Uploads an audio file from a given URL to the NigeriaBulkSMS platform.

• $url (string): The URL of the audio file (e.g., https://example.com/audio.mp3).

$response = $client->audio()->upload("https://example.com/my_audio.mp3");
// The response will contain a 'reference' which can be used with sendAudio.

Data Fetcher Service

Access data fetching functionalities via $client->dataFetcher().

getBalance()

Retrieves the current account balance.

$balance = $client->dataFetcher()->getBalance();

getProfile()

Retrieves the customer profile information.

$profile = $client->dataFetcher()->getProfile();

getContacts()

Retrieves the list of contacts.

$contacts = $client->dataFetcher()->getContacts();

getNumbers()

Retrieves the list of saved numbers.

$numbers = $client->dataFetcher()->getNumbers();

getGroups()

Retrieves the list of groups.

$groups = $client->dataFetcher()->getGroups();

getAudios()

Retrieves the list of saved audio files.

$audios = $client->dataFetcher()->getAudios();

getHistory()

Retrieves the message history.

$history = $client->dataFetcher()->getHistory();

getScheduled()

Retrieves the list of scheduled messages.

$scheduled = $client->dataFetcher()->getScheduled();

getReports()

Retrieves the delivery reports.

$reports = $client->dataFetcher()->getReports();

getPayments()

Retrieves the payment history.

$payments = $client->dataFetcher()->getPayments();

Error Handling

The SDK throws NigeriaBulkSMSException for API-specific errors. You should wrap your API calls in try-catch blocks to handle these exceptions gracefully.

<?php

use NigeriaBulkSMS\NigeriaBulkSMS;
use NigeriaBulkSMS\Exception\NigeriaBulkSMSException;

$client = new NigeriaBulkSMS("YOUR_USERNAME", "YOUR_PASSWORD");

try {
    $response = $client->sms()->send("Test message", "TestApp", "2348000000000");
    print_r($response);
} catch (NigeriaBulkSMSException $e) {
    echo "API Error: " . $e->getMessage() . " (Code: " . $e->getCode() . ")\n";
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    echo "HTTP Error: " . $e->getMessage() . "\n";
} catch (Exception $e) {
    echo "General Error: " . $e->getMessage() . "\n";
}

?>

Common error codes are:

• 100: Incomplete request parameters
• 101: Request denied
• 110: Login status failed
• 111: Login status denied
• 150: Insufficient funds
• 191: Internal error

For a full list of error codes, refer to the official NigeriaBulkSMS API documentation.

Contributing

Feel free to contribute to this SDK by submitting issues or pull requests on GitHub.

License

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

Author: Timothy Dake

• LinkedIn: https://www.linkedin.com/in/timothy-dake-14801571/
• X (formerly Twitter): @timothydake
• Email: [e-mail]