README

The Swiftsms-GH PHP SDK provides a suitable approach to the Swiftsms-GH API from applications written in PHP. It includes pre-defined set of classes and functions for API resource that initialize themselves from API responses.

The library provides other features. For Example:

1. Easy configuration path for fast setup and use
2. Helpers for pagination.

You can sign up for an Swiftsms-GH account at swiftsmsgh.com

Table of Contents

• Prerequisites
• Installation
• Documentation
• Usage
• Exception Handling
• HTTP Endpoints
• Send Messages
  • Send SMS
  • Schedule Message & Custom Sender ID
  • Send Voice Call
  • Send MMS
  • Send OTP
  • Send WhatsApp
  • Send Viber
• Contacts Management
  • Contact Groups
  • Individual Contacts
• Check SMS Credit Balance
• View Profile
• Status Codes
• Response Examples
• Contributing
• Changelog
• License

Prerequisites

PHP ^8.0 and later

Installation

Via Composer

$ composer require swiftsmsgh/swiftsmsgh-api-sdk

Via Git Bash

git clone git@github.com:supreme-majesty/swiftsmsgh-api-sdk.git

Documentation

Please see https://swiftsmsgh.com/developer for up-to-date documentation

Usage

Step 1:

If you install the Swiftsms-GH PHP SDK via Git Clone then load the Swiftsms-GH PHP API class file and use namespace.

require_once '/path/to/src/Swiftsmsgh.php';
use Swiftsms\Swiftsmsgh;

If you install Swiftsms-GH PHP SDK via Composer require the autoload.php file in the index.php of your project or whatever file you need to use Swiftsms-GH PHP API classes.

require __DIR__ . '/vendor/autoload.php';
use Swiftsms\Swiftsmsgh;

The Swiftsms-GH PHP SDK endpoints are RESTful, and consume and return JSON. All Http endpoints requires an API Key in the request header.

For more information on how to get an API Key visit here to copy or generate new key for authorization.

Exception Handling

The SDK throws Swiftsms\SwiftsmsException when an API or network error occurs.

try {
    $response = $client->send_sms($recipients, $message);
} catch (Swiftsms\SwiftsmsException $e) {
    echo "Error: " . $e->getMessage();
}

HTTP Endpoints

• https://swiftsmsgh.com/api/v3/sms/send
• https://swiftsmsgh.com/api/v3/sms/{uid}
• https://swiftsmsgh.com/api/v3/sms
• https://swiftsmsgh.com/api/v3/me
• https://swiftsmsgh.com/api/v3/balance
• https://swiftsmsgh.com/api/v3/contacts
• https://swiftsmsgh.com/api/v3/contacts/{group_id}/show/
• https://swiftsmsgh.com/api/v3/contacts/{group_id}
• https://swiftsmsgh.com/api/v3/contacts/{group_id}/store
• https://swiftsmsgh.com/api/v3/contacts/{group_id}/search/{uid}
• https://swiftsmsgh.com/api/v3/contacts/{group_id}/update/{uid}
• https://swiftsmsgh.com/api/v3/contacts/{group_id}/delete/{uid}
• https://swiftsmsgh.com/api/v3/contacts/{group_id}/all

Step 2:

Instantiate the SwiftsmsghSMSSDKAPI

$api_token = "Enter Your API Token here";

$sender_id = "Enter your approved Sender ID here";

$client = new Swiftsms\Swiftsmsgh($api_token, $sender_id);

Send Messages

1. Send SMS

$recipients = "233538000000,233540000000";
$message = "This is a test message";

$response = $client->send_sms($recipients, $message);

2. Schedule Message & Custom Sender ID

You can pass an optional $options array to any sending method.

$options = [
    'schedule_time' => '2025-12-25 08:00', // Format: Y-m-d H:i
    'sender_id'     => 'MyAlert'           // Override default Sender ID
];

$client->send_sms($recipients, $message, $options);

3. Send Voice Call

// gender: 'male' or 'female'
// language: 'en-gb', 'en-us', etc.
$client->send_voice($recipients, "Wake up!", "female", "en-gb");

4. Send MMS

$mediaUrl = "https://example.com/image.jpg";
$client->send_mms($recipients, "Here is the photo", $mediaUrl);

5. Send OTP

$client->send_otp($recipients, "Your verification code is 1234");

6. Send WhatsApp

$client->send_whatsapp($recipients, "Hello from WhatsApp API");

7. Send Viber

$client->send_viber($recipients, "Hello from Viber API");

Contacts Management

Contact Groups

// Get all contact groups
$groups = $client->all_contact_groups();

// View a specific contact group
$group = $client->view_contact_group($group_id);

// Create a new contact group
$client->create_contact_group($phones, $groupName);

// Update a contact group
$client->update_contact_group($phones, $groupName);

// Delete a contact group
$client->delete_contact_group($group_id);

Individual Contacts

// Get all contacts in a group
$contacts = $client->all_contacts_in_group($group_id);

// View a specific contact
$contact = $client->view_contact($group_id, $uid);

// Create a new contact
$client->create_contact($phones, $message);

// Update a contact
$client->update_contact($phones, $message);

// Delete a contact
$client->delete_contact($group_id, $uid);

Check SMS Credit Balance

$get_credit_balance = $client->check_balance();

View Profile

$get_profile = $client->profile();

Status Codes

Response Examples

Successful SMS Send

{
    "status": "ok",
    "message": "Successfully Send",
    "data": {
        "uid": "abc123xyz",
        "to": "233538000000",
        "message": "This is a test message",
        "status": "delivered"
    }
}

Balance Check

{
    "status": "ok",
    "data": {
        "remaining_balance": 150.5,
        "currency": "GHS"
    }
}

Error Response

{
    "status": "error",
    "code": 102,
    "message": "Authentication failed"
}

Contributing

Please see CONTRIBUTING.md for details on how to contribute to this project.

Changelog

Please see CHANGELOG.md for a list of changes.

License

This project is licensed under the MIT License - see the LICENSE file for details.