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 [email protected] 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