NigeriaBulkSMS Flutter SDK #

A production-grade Flutter/Dart 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 Flutter 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
• 🎯 Type-safe - Built with Dart for better developer experience

Installation #

Add this to your package's pubspec.yaml file:

dependencies:
  nigeriabulksms_sdk: ^0.1.0

Then, run flutter pub get in your project directory.

Basic Usage #

First, import the package and initialize the NigeriaBulkSMSClient with your username and password.

import 'package:nigeriabulksms_sdk/nigeriabulksms_sdk.dart';

void main() async {
  final client = NigeriaBulkSMSClient(
    username: 'YOUR_USERNAME',
    password: 'YOUR_PASSWORD',
  );

  try {
    // Send an SMS
    final smsResponse = await client.sms.send(
      message: 'Hello from Flutter SDK!',
      sender: 'FlutterApp',
      mobiles: '2348030000000',
    );
    print('SMS sent successfully: ${smsResponse}');

    // Get account balance
    final balanceResponse = await client.data.getBalance();
    print('Account Balance: ${balanceResponse}');

  } on NigeriaBulkSMSException catch (e) {
    print('Error: ${e.message} (Code: ${e.code})');
  } catch (e) {
    print('An unexpected error occurred: ${e}');
  } finally {
    client.close();
  }
}

API Reference #

NigeriaBulkSMSClient #

The main client class to interact with the NigeriaBulkSMS API.

NigeriaBulkSMSClient({
  required String username,
  required String password,
  String baseUrl = 'https://portal.nigeriabulksms.com/api/',
})

SMS Service (client.sms) #

send({required String message, required String sender, required dynamic 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 or List<String>): A single mobile number string or a list of mobile number strings. Numbers should be in international format (e.g., 2348030000000).

final smsResponse = await client.sms.send(
  message: 'Your message',
  sender: 'SenderID',
  mobiles: '2348030000000',
);
// Or for multiple recipients:
final smsResponse = await client.sms.send(
  message: 'Your message',
  sender: 'SenderID',
  mobiles: ['2348030000000', '2348020000000'],
);

Call Service (client.call) #

sendTTS({required String message, required String sender, required dynamic 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 or List<String>): A single mobile number string or a list of mobile number strings.

final ttsResponse = await client.call.sendTTS(
  message: 'Hello, this is a test call.',
  sender: 'YourApp',
  mobiles: '2348030000000',
);

sendAudio({required String audioReference, required String sender, required dynamic 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 or List<String>): A single mobile number string or a list of mobile number strings.

final audioResponse = await client.call.sendAudio(
  audioReference: 'your-audio-reference-id',
  sender: 'YourApp',
  mobiles: '2348030000000',
);

Audio Service (client.audio) #

upload({required 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).

final uploadResponse = await client.audio.upload(
  url: 'https://example.com/my_audio.mp3',
);
// The response will contain a 'reference' which can be used with sendAudio.

Data Service (client.data) #

getBalance()

Retrieves the current account balance.

final balance = await client.data.getBalance();

getProfile()

Retrieves the customer profile information.

final profile = await client.data.getProfile();

getContacts()

Retrieves the list of contacts.

final contacts = await client.data.getContacts();

getNumbers()

Retrieves the list of saved numbers.

final numbers = await client.data.getNumbers();

getGroups()

Retrieves the list of groups.

final groups = await client.data.getGroups();

getAudios()

Retrieves the list of saved audio files.

final audios = await client.data.getAudios();

getHistory()

Retrieves the message history.

final history = await client.data.getHistory();

getScheduled()

Retrieves the list of scheduled messages.

final scheduled = await client.data.getScheduled();

getReports()

Retrieves the delivery reports.

final reports = await client.data.getReports();

getPayments()

Retrieves the payment history.

final payments = await client.data.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.

import 'package:nigeriabulksms_sdk/nigeriabulksms_sdk.dart';

void main() async {
  final client = NigeriaBulkSMSClient(
    username: 'YOUR_USERNAME',
    password: 'YOUR_PASSWORD',
  );

  try {
    final response = await client.sms.send(
      message: 'Test message',
      sender: 'TestApp',
      mobiles: '2348000000000',
    );
    print(response);
  } on NigeriaBulkSMSException catch (e) {
    print('API Error: ${e.message} (Code: ${e.code})');
  } catch (e) {
    print('General Error: ${e}');
  } finally {
    client.close();
  }
}

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: timdake4@gmail.com