Skip to main content

Node.js SDK (NPM)

npm version License: MIT

This is the official Node.js/TypeScript SDK for interacting with the Notify Africa API, focused on SMS messaging. It provides a simple class‑based interface for sending single or batch SMS messages and checking message status. Built on native fetch for zero external dependencies (Node.js >= 18).

Repository

Features​

  • Send single SMS messages
  • Send batch SMS messages to multiple recipients
  • Check the status of sent messages
  • Configurable base URL (defaults to https://api.notify.africa)
  • TypeScript support with full type definitions
  • No external runtime dependencies (uses native fetch)

Installation​

npm install notify-africa
# or
yarn add notify-africa
# or
pnpm add notify-africa

Quick Start​

import { NotifyAfrica } from 'notify-africa';

const notifyAfrica = new NotifyAfrica(
  process.env.NOTIFY_API_TOKEN || 'your-token-here'
  // Optional: you can pass a custom base URL as the second argument
  // 'https://api.notify.africa'
);

async function run() {
  // Send a single message
  const single = await notifyAfrica.sendSingleMessage(
    '255689737459',
    'Hello from API Management endpoint!',
    '137'
  );
  console.log(single); // { messageId: '156023', status: 'PROCESSING' }

  // Send a batch
  const batch = await notifyAfrica.sendBatchMessages(
    ['255763765548', '255689737839'],
    'test',
    '137'
  );
  console.log(batch); // { messageCount: 2, creditsDeducted: 2, remainingBalance: 1475 }

  // Check status
  const status = await notifyAfrica.checkMessageStatus('156022');
  console.log(status); // { messageId: '156022', status: 'SENT', sentAt: null, deliveredAt: '2025-11-13T12:34:08.540Z' }
}

run().catch(console.error);

Configuration​

  • API token: store in an environment variable and pass to the constructor.
  • Base URL: optional override when using staging/regional endpoints.
// Env (example)
// export NOTIFY_API_TOKEN="ntfy_..."

import { NotifyAfrica } from 'notify-africa';
const client = new NotifyAfrica(process.env.NOTIFY_API_TOKEN!, /* baseUrl? */);

API Reference (summary)​

// Constructor
// new NotifyAfrica(apiToken: string, baseUrl?: string)
// - apiToken: Your Notify Africa API bearer token (required)
// - baseUrl: Optional; defaults to 'https://api.notify.africa'

// Methods
// 1) Sends a single SMS
// sendSingleMessage(
//   phoneNumber: string,
//   message: string,
//   senderId: string,
// ): Promise<{ messageId: string; status: string }>

// 2) Sends SMS to multiple recipients
// sendBatchMessages(
//   phoneNumbers: string[],
//   message: string,
//   senderId: string,
// ): Promise<{ messageCount: number; creditsDeducted: number; remainingBalance: number }>

// 3) Retrieves the status of a message
// checkMessageStatus(
//   messageId: string,
// ): Promise<{ messageId: string; status: string; sentAt: string | null; deliveredAt: string | null }>

NestJS Example​

import { Injectable } from '@nestjs/common';
import { NotifyAfrica } from 'notify-africa';

@Injectable()
export class SmsService {
  private client: NotifyAfrica;

  constructor() {
    this.client = new NotifyAfrica(process.env.NOTIFY_API_TOKEN!);
  }

  async sendSingle(phone: string, message: string, senderId: string) {
    return this.client.sendSingleMessage(phone, message, senderId);
  }
}

Requirements​

  • Node.js >= 18.0.0 (native fetch)

Troubleshooting​

  • Ensure your API token is set and passed as a Bearer token.
  • Phone numbers must be in international format (e.g., 255...).
  • If you receive PROCESSING status, use the status endpoint to poll for updates.
  • Network/proxy issues: verify your server can reach https://api.notify.africa.

License​

MIT License. See LICENSE in the repository.

Support​