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

// Rate limit info
if ($response->rateLimitInfo) {
    echo $response->rateLimitInfo->remaining; // 9
    echo $response->rateLimitInfo->limit;     // 10
}

Verify OTP

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

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

// Rate limit info
if ($response->rateLimitInfo) {
    echo $response->rateLimitInfo->remaining; // 8
}

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
}

Rate Limit Errors

When OTP rate limits are exceeded, the exception includes retryAfter (seconds until lockout expires):

use GoSmsGe\SmsSDK\Exception\TooManyRequestsException;
use GoSmsGe\SmsSDK\Exception\AccountLockedException;

try {
    $response = $client->sendOtp('995555123456');
} catch (TooManyRequestsException $e) {
    echo 'Too many attempts. Retry after ' . $e->getRetryAfter() . 's';
} catch (AccountLockedException $e) {
    echo 'Account locked. Retry after ' . $e->getRetryAfter() . 's';
}

Error Code Reference

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