README

Official PHP SDK for the GoSMS.ge SMS Gateway API.

Requirements

PHP 7.4 or higher
A PSR-18 HTTP client (e.g., Guzzle, Symfony HttpClient)
A PSR-17 HTTP factory (e.g., nyholm/psr7, guzzlehttp/psr7)

Installation

composer require gosms-ge/sms-sdk

You also need a PSR-18 HTTP client. If you don't have one:

composer require guzzlehttp/guzzle

Or with Symfony:

composer require symfony/http-client nyholm/psr7

Quick Start

<?php

use GoSmsGe\SmsSDK\GoSmsClient;

$client = new GoSmsClient('your-api-key');

// Send SMS
$response = $client->sendSms('MYBRAND', '995555123456', 'Hello!');
echo $response->messageId; // 12345
echo $response->balance;   // 4999

Usage

Send SMS

$response = $client->sendSms('MYBRAND', '995555123456', 'Hello!');

// With urgent flag
$response = $client->sendSms('MYBRAND', '995555123456', 'Urgent!', true);

$response->success;       // bool
$response->messageId;     // int
$response->from;          // string
$response->to;            // string
$response->text;          // string
$response->sendAt;        // string (ISO 8601)
$response->balance;       // int
$response->encode;        // "default" or "Unicode"
$response->segment;       // int
$response->smsCharacters; // int

Send Bulk SMS

$response = $client->sendBulkSms(
    'MYBRAND',
    ['995555111111', '995555222222', '995555333333'],
    'Sale today!'
);

$response->totalCount;   // 3
$response->successCount; // 3
$response->failedCount;  // 0

foreach ($response->messages as $msg) {
    echo $msg->messageId . ' -> ' . $msg->to;
    if (!$msg->success) {
        echo ' FAILED: ' . $msg->error;
    }
}

Check SMS Status

$response = $client->checkSms(12345);

$response->status; // "IN_PROGRESS", "DELIVERED", "REJECTED", "EXPIRED", "QUEUE", "ENROUTE"

Check Balance

$response = $client->getBalance();

$response->balance; // 5000

Send OTP

$response = $client->sendOtp('995555123456');

$response->hash;    // "abc123..." — save this for verification
$response->balance; // 4999

Verify OTP

$response = $client->verifyOtp('995555123456', $hash, '1234');

if ($response->verify) {
    echo 'OTP verified!';
} else {
    echo 'Wrong code';
}

Note: A wrong OTP code returns verify: false without throwing an exception. Exceptions are thrown only for expired OTPs, already-used OTPs, and locked accounts.

Create Sender

$response = $client->createSender('NewBrand');

$response->success; // true

Error Handling

All API errors throw specific exceptions that extend ApiException:

use GoSmsGe\SmsSDK\Exception\ApiException;
use GoSmsGe\SmsSDK\Exception\InsufficientBalanceException;
use GoSmsGe\SmsSDK\Exception\InvalidPhoneException;
use GoSmsGe\SmsSDK\Exception\NetworkException;

try {
    $client->sendSms('MYBRAND', '995555123456', 'Hello!');
} catch (InsufficientBalanceException $e) {
    // Handle low balance
} catch (InvalidPhoneException $e) {
    // Handle bad phone number
} catch (ApiException $e) {
    // Catch-all for any API error
    echo $e->getErrorCode();    // int (100-113)
    echo $e->getErrorMessage(); // string
} catch (NetworkException $e) {
    // Transport failure or invalid JSON response
}

Error Code Reference

Code	Exception	Description
100	`InvalidApiKeyException`	Invalid or missing API key
101	`InvalidSenderException`	Invalid sender name
102	`InsufficientBalanceException`	Not enough SMS balance
103	`InvalidParametersException`	Invalid parameters or message too long
104	`MessageNotFoundException`	Message ID not found
105	`InvalidPhoneException`	Invalid phone number format
106	`OtpFailedException`	Failed to generate/send OTP
107	`SenderExistsException`	Sender name already exists
108	`NotConfiguredException`	API token not configured for this operation
109	`TooManyRequestsException`	Too many OTP requests (rate limited)
110	`AccountLockedException`	Account locked (too many failed attempts)
111	`OtpExpiredException`	OTP code expired
112	`OtpAlreadyUsedException`	OTP code already used
113	`InvalidNoSmsNumberException`	Invalid noSmsNumber parameter

Custom HTTP Client

The SDK auto-detects your installed PSR-18 HTTP client. To provide a custom one:

use GoSmsGe\SmsSDK\GoSmsClient;
use GuzzleHttp\Client as Guzzle;

$guzzle = new Guzzle(['timeout' => 10]);

$client = new GoSmsClient(
    'your-api-key',
    'https://api.gosms.ge',
    $guzzle
);

Custom Base URL

$client = new GoSmsClient('your-api-key', 'https://your-custom-endpoint.com');

Laravel Integration

// In AppServiceProvider::register()
$this->app->singleton(GoSmsClient::class, function () {
    return new GoSmsClient(config('services.gosms.api_key'));
});

// In your controller
public function send(GoSmsClient $gosms)
{
    $gosms->sendSms('MYBRAND', $request->phone, 'Your code is 1234');
}

Phone Number Format

The API accepts Georgian mobile numbers in two formats:

9 digits starting with 5: 555123456
12 digits with country code: 995555123456

SMS Limits

GSM-7 (default): 160 chars per segment, max 918 chars (6 segments)
Unicode: 70 chars per segment, max 402 chars (6 segments)
Encoding is detected automatically by the API

License

MIT

gosms-ge / sms-sdk

Maintainers

Details