Skip to main content

PHP SDK

License: MIT Packagist

A modern PHP 8.1+ SDK for integrating with the Notify Africa SMS HTTP API. This library provides a convenient, typed API for sending single or bulk SMS messages with robust error handling and first-class testing support.

Repository

Features​

  • Typed configuration, request, and response objects
  • Configurable timeouts and HTTP layer (Guzzle by default)
  • Batch and single message support
  • Domain-specific exceptions for authentication, validation, and HTTP issues
  • PSR-3 logging integration

Requirements​

  • PHP >= 8.1
  • Composer

Installation​

composer require ipfsoftwares/notify-africa-php:dev-main

Quick Start​

<?php

use NotifyAfrica\Sms\ClientConfig;
use NotifyAfrica\Sms\NotifyAfricaClient;

use NotifyAfrica\Sms\Request\SingleMessageRequest;


$config = new ClientConfig(

    apiToken: 'your-api-token',

    baseUri: 'https://api.notify.africa',
);

$client = new NotifyAfricaClient($config);


$response = $client->sendSingleMessage(
    new SingleMessageRequest(
        phoneNumber: '255689737459',
        message: 'Hello from SDK!',
        senderId: '137',
    )
);

printf('Message ID: %s', $response->getMessageId());

Usage​

Sending a Single SMS​

use NotifyAfrica\Sms\Request\SingleMessageRequest;

$response = $client->sendSingleMessage(
    new SingleMessageRequest(
        phoneNumber: '255689737459',
        message: 'Hello from SDK!',
        senderId: '137',
    )
);


echo $response->getMessageId();

Sending Batch SMS​

use NotifyAfrica\Sms\Request\BatchMessageRequest;

$response = $client->sendBatchMessages(
    new BatchMessageRequest(
        phoneNumbers: ['255763765548', '255689737839'],
        message: 'Promotional offer',
        senderId: '137',
    )
);

echo $response->getBatchId();

Error Handling​

Wrap calls in a try/catch block to handle failures:

use NotifyAfrica\Sms\Exception\AuthenticationException;
use NotifyAfrica\Sms\Exception\ValidationException;
use NotifyAfrica\Sms\Exception\HttpRequestException;

try {
    $client->sendSingleMessage($request);
} catch (AuthenticationException $exception) {
    // invalid token or insufficient permissions
} catch (ValidationException $exception) {
    // request payload issues
} catch (HttpRequestException $exception) {
    // network or unexpected API response
}

Configuration​

ClientConfig accepts the following options:

  • apiToken (string): Required Notify Africa API token
  • baseUri (string): Base API URL (default: https://api.notify.africa)
  • timeout (float): Request timeout in seconds (default: 10.0)
  • connectTimeout (float): Connection timeout in seconds (default: 5.0)
  • logger (LoggerInterface): Optional PSR-3 logger (default: Psr\\Log\\NullLogger)

Example:

use NotifyAfrica\Sms\ClientConfig;
use NotifyAfrica\Sms\NotifyAfricaClient;

$config = new ClientConfig(
    apiToken: getenv('NOTIFY_AFRICA_API_TOKEN'),
    baseUri: 'https://api.notify.africa',
    timeout: 10.0,
    connectTimeout: 5.0,
);
$client = new NotifyAfricaClient($config);

Examples​

The repository examples/ directory contains runnable scripts:

  • examples/send_single.php
  • examples/send_batch.php

Run them with:

php examples/send_single.php
php examples/send_batch.php

Troubleshooting​

  • Ensure your API token is valid and provided via Authorization: Bearer <token> header (handled by the SDK)
  • Phone numbers must be in international format without + (e.g., 255...)
  • If you receive PROCESSING status, use the status endpoint to poll for updates (if exposed by the SDK)
  • Networking issues: verify your server can reach https://api.notify.africa

License​

MIT License. See LICENSE in the repository.

Support​

For SDK-specific issues, open an issue: notify-africa-php/issues

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