README

A clean and simple PHP client library for integrating with the Zamtel Bulk SMS API. Send SMS messages, check account balance, and manage sender IDs with ease.

Features

• Send SMS to single or multiple recipients
• Check account balance
• Create and manage sender IDs
• Phone number validation and formatting
• Built on Guzzle HTTP client
• Simple and intuitive API

Requirements

• PHP 7.4 or higher
• Composer
• Guzzle HTTP Client 7.0 or higher

Installation

Install the package via Composer:

composer require xililo/zamtel-sms

Quick Start

<?php

require 'vendor/autoload.php';

use xililo\ZamtelSms\ZamtelSmsClient;

// Initialize the client
$client = new ZamtelSmsClient(
    'your-api-key-here',
    'YourSenderID' // Optional: default sender ID
);

// Send an SMS
$result = $client->sendSms('260951234567', 'Hello from Zamtel SMS!');

Usage

Initialization

use xililo\ZamtelSms\ZamtelSmsClient;

// With default sender ID
$client = new ZamtelSmsClient('your-api-key', 'YourSenderID');


// Without default sender ID (NOTE: must provide sender ID in each `sendSms` call)
$client = new ZamtelSmsClient('your-api-key');
// Then you need to provide the `SenderID` when sending. Like this:
$result = $client->sendSms(
    '260951234567',
    'Hello!',
    'SenderID' // <--- THIS RIGHT HERE.
    );

// ADVANCED: With custom HTTP client
$customClient = new \GuzzleHttp\Client([...]); // If you have custom configs to set.
$client = new ZamtelSmsClient('your-api-key', 'YourSenderID', $customClient);

Sending SMS

Send to a single recipient

$result = $client->sendSms('260951234567', 'Hello, this is a test message!');

Send to multiple recipients

$contacts = ['260951234567', '260971234567', '260961234567'];
$result = $client->sendSms($contacts, 'Hello everyone!');

Send with a specific sender ID

$result = $client->sendSms(
    '260951234567',
    'Hello!',
    'CustomSenderID'
);

Response Format

All methods return an array with the following structure:

[
    'success' => true,           // Boolean: true if HTTP status is 2xx
    'http_code' => 200,          // HTTP status code
    'response' => [...],         // Decoded JSON response or raw string
    'raw_response' => '...'      // Raw response body
]

Checking Account Balance

$balance = $client->getBalance();

if ($balance['success']) {
    echo "Balance: " . json_encode($balance['response']);
}

Managing Sender IDs

Create a new sender ID

$result = $client->createSenderId('MyNewSenderID');

Set default sender ID

$client->setDefaultSenderId('MyDefaultSenderID');

Get current default sender ID

$senderId = $client->getDefaultSenderId();

Phone Number Utilities

Validate Zambian phone number

if (ZamtelSmsClient::isValidZambianNumber('260951234567')) {
    echo "Valid number!";
}

Format phone number to Zambian format

// Formats various formats to 260XXXXXXXXX
$formatted = ZamtelSmsClient::formatPhoneNumber('0951234567');  // 260951234567
$formatted = ZamtelSmsClient::formatPhoneNumber('+260 95 123 4567');  // 260951234567
$formatted = ZamtelSmsClient::formatPhoneNumber('260-95-123-4567');  // 260951234567

Error Handling

try {
    $result = $client->sendSms('260951234567', 'Hello!');

    if ($result['success']) {
        echo "SMS sent successfully!";
    } else {
        echo "Failed: " . json_encode($result['response']);
    }
} catch (Exception $e) {
    echo "Error: " . $e->getMessage();
}

API Reference

Methods

sendSms($contacts, string $message, ?string $senderId = null): array

Send SMS to one or multiple contacts.

Parameters:

• $contacts (string|array): Single phone number or array of phone numbers
• $message (string): The SMS message content
• $senderId (string|null): Optional sender ID (uses default if not provided)

Returns: Array with response data

Throws: Exception if contacts are empty or sender ID is missing

getBalance(): array

Query SMS account balance.

Returns: Array with balance information

Throws: Exception on HTTP request failure

createSenderId(string $senderId): array

Create a new sender ID.

Parameters:

• $senderId (string): The sender ID to create

Returns: Array with response data

Throws: Exception if sender ID is empty or request fails

setDefaultSenderId(string $senderId): self

Set the default sender ID for subsequent SMS sends.

Parameters:

• $senderId (string): The sender ID to set as default

Returns: Self instance for method chaining

getDefaultSenderId(): ?string

Get the current default sender ID.

Returns: Default sender ID string or null

getHttpClient(): Client

Get the underlying Guzzle HTTP client instance.

Returns: GuzzleHttp\Client instance

isValidZambianNumber(string $phoneNumber): bool (static)

Validate if a phone number matches Zambian format (260 followed by 9 digits).

Parameters:

• $phoneNumber (string): Phone number to validate

Returns: Boolean indicating validity

formatPhoneNumber(string $phoneNumber): string (static)

Format a phone number to Zambian international format (260XXXXXXXXX).

Parameters:

• $phoneNumber (string): Phone number to format

Returns: Formatted phone number string

Phone Number Format

Zambian phone numbers should be in the format: 260XXXXXXXXX

• Country code: 260
• Followed by 9 digits
• Example: 260951234567

The library includes utilities to validate and format phone numbers automatically.

License

This package is open-sourced software. Please check the license file for more details.

Author

xililo

• Email: sililosililo82@gmail.com

Support

For issues, questions, or contributions, please open an issue on the repository.