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

Libraries

nigeriabulksms_sdk