NigeriaBulkSMS SDK

A production-grade Node.js 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 Node.js applications.

Features

🚀 Easy to use - Simple and intuitive API
🔒 Type-safe - Built with TypeScript for better developer experience
🛡️ Robust error handling - Comprehensive error types and validation
🔄 Automatic retries - Built-in retry logic with exponential backoff
📱 SMS & Voice - Support for text messages, voice calls, and TTS
📊 Data fetching - Access to account balance, history, and more
✅ Well tested - Comprehensive test suite with high coverage
📚 Full documentation - Complete API documentation and examples

Installation

npm install nigeriabulksms-sdk

Quick Start

import { NigeriaBulkSMSClient } from 'nigeriabulksms-sdk';

// Initialize the client
const client = new NigeriaBulkSMSClient({
    username: 'your-username',
    password: 'your-password'
});

// Send an SMS
async function sendSMS() {
    try {
        const response = await client.sms.send({
            message: 'Hello from NigeriaBulkSMS SDK!',
            sender: 'YourApp',
            mobiles: '2348030000000,2348020000000'
        });
        console.log('SMS sent successfully:', response);
    } catch (error) {
        console.error('Error sending SMS:', error.message);
    }
}

sendSMS();

Configuration

Basic Configuration

const client = new NigeriaBulkSMSClient('username', 'password');

Advanced Configuration

const client = new NigeriaBulkSMSClient({
    username: 'your-username',
    password: 'your-password',
    baseUrl: 'https://portal.nigeriabulksms.com/api/', // Optional
    timeout: 30000, // Optional (30 seconds)
    retries: 3 // Optional (number of retries)
});

API Reference

SMS Service

Send SMS

const response = await client.sms.send({
    message: 'Your message here',
    sender: 'YourApp', // Max 11 alphanumeric characters
    mobiles: '2348030000000,2348020000000', // Comma-separated numbers
    contacts: '1,2,3', // Optional: Contact IDs
    groups: '4,5,6', // Optional: Group IDs
    numbers: '7,8,9' // Optional: Number IDs
});

Voice Service

Send Voice Call

// First, upload an audio file
const uploadResponse = await client.voice.uploadAudio({
    url: 'https://example.com/audio.mp3'
});

// Then send the call using the audio reference
const callResponse = await client.voice.sendCall({
    message: uploadResponse.data.reference, // Audio reference from upload
    sender: 'YourApp',
    mobiles: '2348030000000'
});

Send Text-to-Speech (TTS)

const ttsResponse = await client.voice.sendTTS({
    message: 'Hello, this is a text-to-speech message',
    sender: 'YourApp',
    mobiles: '2348030000000'
});

Upload Audio File

const uploadResponse = await client.voice.uploadAudio({
    url: 'https://example.com/your-audio-file.mp3'
});

Data Service

Get Account Balance

const balance = await client.data.getBalance();
console.log('Account balance:', balance.balance);

Get Profile Information

const profile = await client.data.getProfile();
console.log('Profile:', profile.data);

Get Message History

const history = await client.data.getHistory();
console.log('Message history:', history.data);

Other Data Methods

// Get contacts
const contacts = await client.data.getContacts();

// Get saved numbers
const numbers = await client.data.getNumbers();

// Get groups
const groups = await client.data.getGroups();

// Get saved audio files
const audios = await client.data.getAudios();

// Get scheduled messages
const scheduled = await client.data.getScheduled();

// Get delivery reports
const reports = await client.data.getReports();

// Get payment history
const payments = await client.data.getPayments();

Error Handling

The SDK provides comprehensive error handling with specific error types:

import { 
    NigeriaBulkSMSError, 
    APIError, 
    ValidationError, 
    AuthenticationError, 
    NetworkError 
} from 'nigeriabulksms-sdk';

try {
    await client.sms.send({
        message: 'Test message',
        sender: 'TestApp',
        mobiles: '2348030000000'
    });
} catch (error) {
    if (error instanceof ValidationError) {
        console.error('Validation error:', error.message);
    } else if (error instanceof AuthenticationError) {
        console.error('Authentication failed:', error.message);
    } else if (error instanceof APIError) {
        console.error('API error:', error.message, 'Code:', error.code);
    } else if (error instanceof NetworkError) {
        console.error('Network error:', error.message);
    } else {
        console.error('Unknown error:', error.message);
    }
}

Phone Number Formats

The SDK automatically formats phone numbers to the correct international format. Supported formats:

08030000000 → 2348030000000
+2348030000000 → 2348030000000
2348030000000 → 2348030000000 (no change)

Multiple numbers should be comma-separated:

mobiles: '08030000000,+2348020000000,2348010000000'

Validation

The SDK includes built-in validation for:

Phone numbers: Must be valid Nigerian phone numbers
Sender ID: Max 11 alphanumeric characters
Message: Max 1600 characters for SMS
URLs: Must be valid HTTP/HTTPS URLs for audio uploads

Testing Connection

try {
    const isConnected = await client.testConnection();
    if (isConnected) {
        console.log('Connection successful!');
    } else {
        console.log('Connection failed');
    }
} catch (error) {
    console.error('Connection test failed:', error.message);
}

Environment Variables

For security, it's recommended to use environment variables:

# .env file
NIGERIABULKSMS_USERNAME=your-username
NIGERIABULKSMS_PASSWORD=your-password

const client = new NigeriaBulkSMSClient({
    username: process.env.NIGERIABULKSMS_USERNAME!,
    password: process.env.NIGERIABULKSMS_PASSWORD!
});

TypeScript Support

This SDK is built with TypeScript and provides full type definitions. All API responses are properly typed:

import { SMSResponse, BalanceResponse } from 'nigeriabulksms-sdk';

const smsResponse: SMSResponse = await client.sms.send({...});
const balanceResponse: BalanceResponse = await client.data.getBalance();

Examples

Complete SMS Example

import { NigeriaBulkSMSClient, ValidationError, APIError } from 'nigeriabulksms-sdk';

async function sendWelcomeSMS() {
    const client = new NigeriaBulkSMSClient({
        username: process.env.NIGERIABULKSMS_USERNAME!,
        password: process.env.NIGERIABULKSMS_PASSWORD!
    });

    try {
        // Check balance first
        const balance = await client.data.getBalance();
        console.log(`Current balance: ${balance.balance}`);

        // Send SMS
        const response = await client.sms.send({
            message: 'Welcome to our service! Thank you for signing up.',
            sender: 'MyApp',
            mobiles: '2348030000000'
        });

        console.log(`SMS sent successfully! Count: ${response.count}, Price: ${response.price}`);
    } catch (error) {
        if (error instanceof ValidationError) {
            console.error('Invalid input:', error.message);
        } else if (error instanceof APIError) {
            console.error('API error:', error.message, 'Code:', error.code);
        } else {
            console.error('Unexpected error:', error.message);
        }
    }
}

sendWelcomeSMS();

Voice Message Example

async function sendVoiceMessage() {
    const client = new NigeriaBulkSMSClient({
        username: process.env.NIGERIABULKSMS_USERNAME!,
        password: process.env.NIGERIABULKSMS_PASSWORD!
    });

    try {
        // Option 1: Upload and use custom audio
        const uploadResponse = await client.voice.uploadAudio({
            url: 'https://example.com/welcome-message.mp3'
        });

        const callResponse = await client.voice.sendCall({
            message: uploadResponse.data!.reference,
            sender: 'MyApp',
            mobiles: '2348030000000'
        });

        console.log('Voice call sent:', callResponse);

        // Option 2: Use Text-to-Speech
        const ttsResponse = await client.voice.sendTTS({
            message: 'Hello, this is an automated message from MyApp.',
            sender: 'MyApp',
            mobiles: '2348030000000'
        });

        console.log('TTS message sent:', ttsResponse);
    } catch (error) {
        console.error('Error sending voice message:', error.message);
    }
}

sendVoiceMessage();

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

Timothy John Dake

GitHub: spaco67
LinkedIn: linkedin.com/in/timothy-dake-14801571

Support

For support, please contact support@nigeriabulksms.com or visit https://nigeriabulksms.com.

Changelog

v1.0.0

Initial release
SMS sending functionality
Voice calling and TTS support
Audio file upload
Data fetching (balance, profile, history, etc.)
Comprehensive error handling
TypeScript support
Full test coverage

Package detail