Skip to main content

SMS API — Developer Guide

Welcome to the Notify Africa Core API! This guide will help you quickly integrate SMS capabilities into your applications using RESTful endpoints. You’ll find example requests, developer tips, important notes, and code snippets for common notification tasks.

Prefer using an SDK?

Use an official SDK for faster integration:

Quick Start​

First, you’ll need an API Token. Please request your token via your admin dashboard or contact your system administrator.

All endpoints expect authorization via a Bearer token header. Always send:

Authorization: Bearer {API-TOKEN}

Replace {API-TOKEN} with your actual API token.

Base URL

All endpoints below are relative to:

https://api.notify.africa/

Endpoints Overview​

ActionEndpointMethod
Send Single SMS/api/v1/api/messages/sendPOST
Send Batch SMS/api/v1/api/messages/batchPOST
Check Message Status/api/v1/api/messages/status/{messageId}GET

Tip: All endpoint paths are relative to the base URL above.

1. Send a Single SMS​

Sends an SMS to one recipient.

Sender ID

Your sender_id should be assigned by Notify Africa.

Example Request (cURL) — Single SMS​

curl -X POST https://api.notify.africa/api/v1/api/messages/send \
  -H "Authorization: Bearer {API-TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "255689737459",
    "message": "Hello from API Management endpoint!",
    "sender_id": "137"
  }'

Response Sample — Single SMS​

{
  "status": 200,
  "message": "SMS sent successfully",
  "timestamp": "2025-11-13T12:36:09.751Z",
  "path": "/api/v1/api/messages/send",
  "data": {
    "messageId": "156023",
    "status": "PROCESSING"
  }
}

Helpful Notes — Single SMS​

  • Phone numbers should be in international format (e.g., 255... for Tanzania).
  • The status field may initially be PROCESSING. Use the status API to track delivery.
  • Ensure Content-Type is set to application/json.
  • Avoid special characters in sender_id and keep messages within SMS length limits (usually 160 chars per segment).

2. Send Batch SMS​

Sends a message to multiple recipients at once.

Example Request (cURL) — Batch SMS​

curl -X POST https://api.notify.africa/api/v1/api/messages/batch \
  -H "Authorization: Bearer {API-TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_numbers": ["255763765548", "255689737839"],
    "message": "test",
    "sender_id": "137"
  }'

Response Sample — Batch SMS​

{
  "status": 200,
  "message": "Batch messages sent successfully",
  "timestamp": "2025-11-13T12:47:09.596Z",
  "path": "/api/v1/api/messages/batch",
  "data": {
    "messageCount": 2,
    "creditsDeducted": 2,
    "remainingBalance": 1475
  }
}

Helpful Notes — Batch SMS​

  • phone_numbers must be an array of valid phone numbers.
  • Each SMS to a recipient will consume one credit; check remainingBalance after a batch send.
  • Errors (such as invalid numbers) will be returned with status ≠ 200 and a descriptive message.

3. Check Message Status​

Track your message using the unique messageId from the send response.

Example Request (cURL)​

curl -X GET https://api.notify.africa/api/v1/api/messages/status/156022 \
  -H "Authorization: Bearer {API-TOKEN}"

Response Sample​

{
  "status": 200,
  "message": "Message status retrieved successfully",
  "timestamp": "2025-11-13T12:48:03.876Z",
  "path": "/api/v1/api/messages/status/156022",
  "data": {
    "messageId": "156022",
    "status": "SENT",
    "sentAt": null,
    "deliveredAt": "2025-11-13T12:34:08.540Z"
  }
}

Status Values​

  • PROCESSING: Message is queued.
  • SENT: Message sent to carrier.
  • DELIVERED: Message received on recipient device.
  • FAILED: Message could not be delivered.

Helpful Notes​

  • Track the deliveredAt timestamp for confirmation.
  • If sentAt is null, the message is not yet sent; re-check after a few seconds.

Pro Tips​

  • Best Practice: Use environment configs to store your API Token, never hard-code in source files.
  • Error Handling: Always check for errors in API responses—unexpected issues such as quota exceeded or invalid parameters are returned with descriptive messages.
  • Rate Limits: Avoid sending too many requests at once. Notify Africa may rate-limit API calls to ensure system stability. Batch requests where possible.
  • Security: Keep your API token confidential; treat it like a password. Rotate regularly for enhanced security.

Example: Using SMS API (Multi-language)​

Send Single SMS​

import axios from 'axios';

const API_TOKEN = process.env.NOTIFY_API_TOKEN;
const BASE_URL = 'https://api.notify.africa/api/v1/api';

async function sendSMS() {
  try {
    const res = await axios.post(
      `${BASE_URL}/messages/send`,
      {
        phone_number: '255689737459',
        message: 'Hello from API!',
        sender_id: '137',
      },
      {
        headers: {
          Authorization: `Bearer ${API_TOKEN}`,
          'Content-Type': 'application/json',
        },
      },
    );
    console.log(res.data);
  } catch (error: any) {
    console.error(error.response?.data || error.message);
  }
}

Send Batch SMS​

async function sendBatchSMS() {
  try {
    const res = await axios.post(
      `${BASE_URL}/messages/batch`,
      {
        phone_numbers: ['255763765548', '255689737839'],
        message: 'Bulk message',
        sender_id: '137',
      },
      {
        headers: {
          Authorization: `Bearer ${API_TOKEN}`,
          'Content-Type': 'application/json',
        },
      },
    );
    console.log(res.data);
  } catch (error: any) {
    console.error(error.response?.data || error.message);
  }
}

Need Help?​

If you need anything, reach us via WhatsApp, phone, or email:

Happy Sending! 🚀