Bulk SMS API Integration Tutorial

curl -X POST https://www.bulksmsnigeria.com/api/v2/sms \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "from": "YourBrand",
    "to": "2348012345678",
    "body": "Hello! This is a test message from BulkSMS Nigeria API."
  }'

{
  "status": "success",
  "code": "BSNG-0000",
  "message": "Message sent successfully",
  "data": {
    "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
    "cost": 6.49,
    "currency": "NGN",
    "recipients_count": 1,
    "gateway_used": "direct-refund",
    "unicode": false,
    "page_count": 1
  }
}

<?php

class BulkSMSNigeria {
    private $apiToken;
    private $baseUrl = 'https://www.bulksmsnigeria.com/api/v2';

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

    private function request($method, $path, $data = null) {
        $ch = curl_init($this->baseUrl . $path);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Authorization: Bearer ' . $this->apiToken,
            'Content-Type: application/json',
            'Accept: application/json'
        ]);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        $result = json_decode($response, true);

        if ($httpCode >= 400) {
            throw new Exception($result['error']['message'] ?? 'Request failed');
        }

        return $result;
    }

    public function sendSMS($from, $to, $body) {
        return $this->request('POST', '/sms', [
            'from' => $from,
            'to' => $to,     // "2348012345678" or ["2348012345678", "2348087654321"]
            'body' => $body
        ]);
    }

    public function getBalance() {
        return $this->request('GET', '/balance');
    }

    public function getDeliveryReport($messageId) {
        return $this->request('GET', '/delivery-reports?message_id=' . urlencode($messageId));
    }
}

// Usage Example
try {
    $sms = new BulkSMSNigeria(getenv('BULKSMS_API_TOKEN'));

    $result = $sms->sendSMS(
        'YourBrand',                                   // Sender ID
        '2348012345678',                               // Recipient(s)
        'Hello from PHP! Your order has been shipped.' // Message
    );

    echo "Message sent! ID: " . $result['data']['message_id'];
    echo "\nCost: ₦" . $result['data']['cost'];

    $balance = $sms->getBalance();
    echo "\nBalance: ₦" . $balance['balance']['total_balance'];

} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

?>

<?php

require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

class BulkSMSClient {
    private $client;

    public function __construct($apiToken) {
        $this->client = new Client([
            'base_uri' => 'https://www.bulksmsnigeria.com/api/v2/',
            'headers' => [
                'Authorization' => 'Bearer ' . $apiToken,
                'Accept' => 'application/json'
            ],
            'timeout' => 30
        ]);
    }

    public function sendSMS($from, $to, $body) {
        try {
            $response = $this->client->post('sms', [
                'json' => [
                    'from' => $from,
                    'to' => $to,
                    'body' => $body
                ]
            ]);

            return json_decode($response->getBody(), true);

        } catch (RequestException $e) {
            if ($e->hasResponse()) {
                $error = json_decode($e->getResponse()->getBody(), true);
                throw new Exception($error['error']['message'] ?? 'Request failed');
            }
            throw $e;
        }
    }
}

// Usage
$sms = new BulkSMSClient(getenv('BULKSMS_API_TOKEN'));
$result = $sms->sendSMS('YourBrand', '2348012345678', 'Hello from Guzzle! Your order has been shipped.');
print_r($result['data']);

?>

import os
import requests

class BulkSMSNigeria:
    def __init__(self, api_token):
        self.base_url = 'https://www.bulksmsnigeria.com/api/v2'
        self.headers = {
            'Authorization': f'Bearer {api_token}',
            'Accept': 'application/json'
        }

    def send_sms(self, sender, recipients, body, **options):
        """
        Send SMS to one or more recipients

        Args:
            sender (str): Approved sender ID (max 11 characters)
            recipients (str or list): Phone number(s)
            body (str): Message text
            **options: Optional parameters, e.g. unicode=True,
                       callback_url='https://...', customer_reference='order-42'

        Returns:
            dict: API response containing message_id, cost, etc.
        """
        payload = {'from': sender, 'to': recipients, 'body': body, **options}

        try:
            response = requests.post(
                f'{self.base_url}/sms',
                headers=self.headers,
                json=payload,
                timeout=30
            )
            response.raise_for_status()
            return response.json()

        except requests.exceptions.HTTPError as e:
            error_data = e.response.json() if e.response is not None else {}
            raise Exception(error_data.get('error', {}).get('message', 'SMS sending failed'))

        except requests.exceptions.RequestException as e:
            raise Exception(f'Network error: {str(e)}')

    def get_balance(self):
        """Get current account balance in naira"""
        response = requests.get(f'{self.base_url}/balance', headers=self.headers, timeout=10)
        response.raise_for_status()
        return response.json()['balance']['total_balance']

    def get_delivery_report(self, message_id):
        """Get delivery report for a specific message"""
        response = requests.get(
            f'{self.base_url}/delivery-reports',
            headers=self.headers,
            params={'message_id': message_id},
            timeout=10
        )
        response.raise_for_status()
        return response.json()['data']


# Usage Example
if __name__ == '__main__':
    sms = BulkSMSNigeria(os.environ['BULKSMS_API_TOKEN'])

    try:
        # Send single SMS
        result = sms.send_sms(
            sender='YourBrand',
            recipients='2348012345678',
            body='Hello from Python! This is a test message.'
        )

        print("✓ Message sent successfully!")
        print(f"  Message ID: {result['data']['message_id']}")
        print(f"  Cost: ₦{result['data']['cost']}")

        # Send to multiple recipients
        bulk_result = sms.send_sms(
            sender='YourBrand',
            recipients=['2348012345678', '2348087654321', '2349012345678'],
            body='Flash sale! 30% off all items today only.'
        )

        print(f"\n✓ Bulk message sent to {bulk_result['data']['recipients_count']} recipients")

        # Check balance
        print(f"\nCurrent Balance: ₦{sms.get_balance()}")

    except Exception as e:
        print(f"✗ Error: {e}")

const axios = require('axios');

class BulkSMSNigeria {
    constructor(apiToken) {
        this.client = axios.create({
            baseURL: 'https://www.bulksmsnigeria.com/api/v2',
            headers: {
                'Authorization': `Bearer ${apiToken}`,
                'Accept': 'application/json'
            },
            timeout: 30000
        });
    }

    async sendSMS(from, to, body, options = {}) {
        try {
            // "to" can be a string or an array of numbers
            const response = await this.client.post('/sms', { from, to, body, ...options });
            return response.data;

        } catch (error) {
            if (error.response) {
                // Server responded with an error
                const { code, error: details } = error.response.data;
                throw new Error(`${code}: ${details?.message || 'SMS sending failed'}`);
            } else if (error.request) {
                // Request made but no response
                throw new Error('No response from server');
            } else {
                // Request setup error
                throw new Error(error.message);
            }
        }
    }

    async getBalance() {
        const response = await this.client.get('/balance');
        return response.data.balance.total_balance;
    }

    async getDeliveryReport(messageId) {
        const response = await this.client.get('/delivery-reports', {
            params: { message_id: messageId }
        });
        return response.data.data;
    }
}

// Usage Example
(async () => {
    const sms = new BulkSMSNigeria(process.env.BULKSMS_API_TOKEN);

    try {
        // Send single SMS
        const result = await sms.sendSMS(
            'YourBrand',
            '2348012345678',
            'Hello from Node.js! This is a test message.'
        );

        console.log('✓ Message sent successfully!');
        console.log(`  Message ID: ${result.data.message_id}`);
        console.log(`  Cost: ₦${result.data.cost}`);

        // Send to multiple recipients
        const bulkResult = await sms.sendSMS(
            'YourBrand',
            ['2348012345678', '2348087654321', '2349012345678'],
            'Flash sale! 30% off all items today only.'
        );

        console.log(`\n✓ Bulk message sent to ${bulkResult.data.recipients_count} recipients`);

        // Check balance
        console.log(`\nCurrent Balance: ₦${await sms.getBalance()}`);

    } catch (error) {
        console.error('✗ Error:', error.message);
    }
})();

// Frontend (JavaScript)
async function sendOTP(phoneNumber) {
    try {
        const response = await fetch('/api/send-otp', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                // Use your app's authentication (session, JWT, etc.)
                'Authorization': `Bearer ${userAuthToken}`
            },
            body: JSON.stringify({ phone: phoneNumber })
        });

        const result = await response.json();

        if (result.success) {
            console.log('OTP sent successfully!');
        } else {
            console.error('Failed to send OTP:', result.message);
        }
    } catch (error) {
        console.error('Error:', error);
    }
}

// Backend (Node.js/Express) - This is where the API token is used
app.post('/api/send-otp', authenticateUser, async (req, res) => {
    const { phone } = req.body;

    // Verify user is authenticated
    if (!req.user) {
        return res.status(401).json({ success: false, message: 'Unauthorized' });
    }

    const otp = generateOTP(); // Generate 6-digit OTP

    try {
        // Call BulkSMS API from backend (secure)
        const sms = new BulkSMSNigeria(process.env.BULKSMS_API_TOKEN);
        await sms.sendSMS('YourApp', phone, `Your YourApp verification code is ${otp}. It expires in 10 minutes.`);

        // Store OTP in session/database for verification
        req.session.otp = otp;

        res.json({ success: true, message: 'OTP sent' });
    } catch (error) {
        res.status(500).json({ success: false, message: 'Failed to send OTP' });
    }
});

// Recipients as comma-separated string
{
  "from": "YourBrand",
  "to": "2348012345678,2348087654321,2349012345678",
  "body": "Flash sale! 30% off all items today only."
}

// Or as array (in JSON)
{
  "from": "YourBrand",
  "to": ["2348012345678", "2348087654321", "2349012345678"],
  "body": "Flash sale! 30% off all items today only."
}

{
  "from": "YourBrand",
  "to": "2348012345678",
  "body": "Ẹ kú àárọ̀! Your order is on its way 🚚",
  "unicode": true
}

// Python example
recipients_data = [
    {"phone": "2348012345678", "name": "John", "amount": "5000"},
    {"phone": "2348087654321", "name": "Sarah", "amount": "3200"},
]

for recipient in recipients_data:
    body = f"Hi {recipient['name']}, your order of ₦{recipient['amount']} has been confirmed!"
    sms.send_sms('ShopEase', recipient['phone'], body)

// GET request to check delivery status
GET https://www.bulksmsnigeria.com/api/v2/delivery-reports?message_id={message_id}

// Optional: per_page (default 100, max 1000) and page for large sends

// Response
{
  "status": "success",
  "code": "BSNG-0000",
  "message": "Delivery report retrieved",
  "data": {
    "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
    "customer_reference": "order-42",
    "summary": {
      "total": 3,
      "delivered": 2,
      "pending": 1,
      "failed": 0
    },
    "reports": [
      { "recipient": "2348012345678", "delivery_status": "delivered" },
      { "recipient": "2348087654321", "delivery_status": "delivered" },
      { "recipient": "2349012345678", "delivery_status": "sent awaiting status" }
    ],
    "pagination": { "current_page": 1, "per_page": 100, "total": 3, "last_page": 1 }
  }
}

// Send with a callback URL and your own reference
{
  "from": "YourBrand",
  "to": "2348012345678",
  "body": "Your order has been shipped and arrives tomorrow.",
  "callback_url": "https://yourapp.com/webhooks/sms",
  "customer_reference": "order-42"
}

// What your callback URL receives
{
  "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
  "recipient": "2348012345678",
  "delivery_status": "delivered",
  "customer_reference": "order-42",
  "callback_url": "https://yourapp.com/webhooks/sms",
  "data": {
    "message_id": "a22f907b-c5aa-44e4-89e4-06fe253e9cbb",
    "recipient": "2348012345678",
    "delivery_status": "delivered",
    "customer_reference": "order-42"
  }
}

// GET request
GET https://www.bulksmsnigeria.com/api/v2/balance

// Response (use balance.total_balance)
{
  "data": {
    "status": "success",
    "message": "Balance Inquiry Successful"
  },
  "balance": {
    "total_balance": 1250,
    "universal_wallet": 1000,
    "sms_wallet": 250,
    "sms_bonus": 0,
    "main_balance": 0,
    "volume_bonus": 0,
    "promo_bonus": 0
  }
}

{
  "status": "error",
  "code": "BSNG-3001",
  "error": {
    "message": "You have Insufficient Funds. You need a total of ₦60.00 to send this message.",
    "code": "BSNG-3001",
    "description": "Insufficient wallet balance"
  }
}

import requests
import time

def send_sms_with_retry(sms_client, sender, recipients, body, max_retries=3):
    """
    Send SMS with automatic retry on transient failures
    """
    for attempt in range(max_retries):
        try:
            # Call the API directly so HTTP status codes reach the handlers below
            response = requests.post(
                f'{sms_client.base_url}/sms',
                headers=sms_client.headers,
                json={'from': sender, 'to': recipients, 'body': body},
                timeout=30
            )
            response.raise_for_status()
            return response.json()

        except requests.exceptions.HTTPError as e:
            status_code = e.response.status_code
            error_data = e.response.json()
            error_message = error_data.get('error', {}).get('message', 'Unknown error')

            if status_code == 400:
                # Bad request - don't retry, fix the request
                raise Exception(f"Invalid request: {error_message}")

            elif status_code == 401:
                # Unauthorized - API token invalid
                raise Exception("Authentication failed. Check your API token.")

            elif status_code == 402:
                # Payment required - top up your wallet
                raise Exception(f"Insufficient balance: {error_message}")

            elif status_code == 403:
                # Forbidden - unregistered sender ID or API access restricted
                raise Exception(f"Access denied: {error_message}")

            elif status_code in (409, 422):
                # Duplicate or invalid message - retrying unchanged won't help
                raise Exception(f"Message rejected ({error_data.get('code')}): {error_message}")

            elif status_code == 429:
                # Rate limit - wait and retry
                wait_time = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
                print(f"Rate limited. Waiting {wait_time}s before retry...")
                time.sleep(wait_time)
                continue

            elif status_code >= 500:
                # Server error - retry with backoff
                if attempt < max_retries - 1:
                    wait_time = 2 ** attempt
                    print(f"Server error. Retrying in {wait_time}s...")
                    time.sleep(wait_time)
                    continue
                else:
                    raise Exception("Server error persists after retries")

            else:
                raise Exception(f"Unexpected error: {error_message}")

        except requests.exceptions.Timeout:
            if attempt < max_retries - 1:
                print(f"Request timeout. Retrying...")
                time.sleep(2)
                continue
            else:
                raise Exception("Request timed out after multiple retries")

        except requests.exceptions.ConnectionError:
            if attempt < max_retries - 1:
                print(f"Connection error. Retrying...")
                time.sleep(2)
                continue
            else:
                raise Exception("Could not connect to API server")

    raise Exception("Failed after maximum retries")

# Usage
try:
    result = send_sms_with_retry(sms, 'YourBrand', '2348012345678', 'Your order has been shipped and arrives tomorrow.')
    print("✓ SMS sent successfully!")
except Exception as e:
    print(f"✗ Failed to send SMS: {e}")
    # Log error, send alert, etc.

// PHP phone number validation
function validateNigerianPhone($phone) {
    // Remove spaces, dashes, parentheses
    $phone = preg_replace('/[^0-9]/', '', $phone);

    // Check format: 234XXXXXXXXXX (13 digits starting with 234)
    // or 0XXXXXXXXXX (11 digits starting with 0)
    if (preg_match('/^234[789][01]\d{8}$/', $phone)) {
        return $phone; // Already in international format
    } elseif (preg_match('/^0[789][01]\d{8}$/', $phone)) {
        return '234' . substr($phone, 1); // Convert to international
    }

    return false; // Invalid format
}

// Usage
$phone = validateNigerianPhone('08012345678');
if ($phone) {
    // Send SMS to $phone (234801234567)
} else {
    // Show error: invalid phone number
}

// Python rate limiting example
import time
from collections import deque

class RateLimiter:
    def __init__(self, max_calls=1000, time_window=60):
        self.max_calls = max_calls
        self.time_window = time_window
        self.calls = deque()

    def wait_if_needed(self):
        now = time.time()

        # Remove old calls outside time window
        while self.calls and self.calls[0] < now - self.time_window:
            self.calls.popleft()

        # If at limit, wait until oldest call expires
        if len(self.calls) >= self.max_calls:
            sleep_time = self.calls[0] + self.time_window - now
            time.sleep(sleep_time)
            self.calls.popleft()

        # Record this call
        self.calls.append(now)

# Usage
limiter = RateLimiter(max_calls=1000, time_window=60)

for phone in large_recipient_list:
    limiter.wait_if_needed()
    sms.send_sms('YourBrand', phone, 'Your appointment is confirmed for tomorrow at 10am.')

// Node.js with Bull Queue
const Queue = require('bull');
const smsQueue = new Queue('sms-sending');

// Producer: Add SMS jobs to queue
async function queueBulkSMS(recipients, body) {
    for (const phone of recipients) {
        await smsQueue.add({
            from: 'YourBrand',
            to: phone,
            body: body
        });
    }
}

// Consumer: Process SMS jobs
smsQueue.process(async (job) => {
    const { from, to, body } = job.data;
    const sms = new BulkSMSNigeria(process.env.BULKSMS_API_TOKEN);

    try {
        await sms.sendSMS(from, to, body);
        return { success: true };
    } catch (error) {
        // Will retry automatically based on queue settings
        throw error;
    }
});

// Python logging example
import logging

logging.basicConfig(
    filename='sms_api.log',
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)

def send_sms_with_logging(sms_client, sender, recipients, body):
    count = len(recipients) if isinstance(recipients, list) else len(recipients.split(','))
    logging.info(f"Sending SMS to {count} recipients")

    try:
        result = sms_client.send_sms(sender, recipients, body)
        logging.info(f"SMS sent successfully. Message ID: {result['data']['message_id']}")
        logging.info(f"Cost: ₦{result['data']['cost']} for {result['data']['page_count']} page(s)")
        return result

    except Exception as e:
        logging.error(f"SMS sending failed: {str(e)}")
        raise

// Check balance before campaign
const balance = await sms.getBalance(); // balance.total_balance in naira
const estimatedCost = recipientCount * 6.49; // your per-page rate × pages

if (balance < estimatedCost) {
    throw new Error(
        `Insufficient balance. Need ₦${estimatedCost} but have ₦${balance}`
    );
}

// Proceed with sending
await sms.sendSMS('YourBrand', recipients, body);