API ინტეგრაციის შესახებ About API Integration

GOSMS.GE API გთავაზობთ პროგრამულ წვდომას ჩვენს რესურსებთან. შესაძლებლობას გაძლებთ მოახდინოთ ჩვენი სერვისის ინტეგრაცია თქვენს სისტემაში და მარტივად მიაწვდინოთ ხმა მომხმარებელს.

GOSMS.GE API provides programmatic access to our resources. It enables you to integrate our service into your system and easily reach your customers.

სერვისის გამოსაყენებლად დაგჭირდებათ ჩვენს სისტემაში რეგისტრაცია და შემდგომ დამატებული API key. დამატებითი კითხვების შემთხვევაში გთხოვთ მოგვმართოთ: [email protected]

To use the service, register and obtain an API key. For additional questions please contact: [email protected]

BIT24 Unity

API Key-ის მიღება How to Get Your API Key

API key საჭიროა ყველა მოთხოვნის ავთენტიფიკაციისთვის. მისი მიღება შესაძლებელია app.gosms.ge-ზე, პირადი კაბინეტის API პარამეტრების განყოფილებაში.

An API key is required to authenticate every request. You can obtain it from your account dashboard at app.gosms.ge under API settings.

1. გადადით app.gosms.ge-ზე და შექმენით ანგარიში, ან შედით არსებულ ანგარიშზე. Go to app.gosms.ge and create an account, or log in to an existing one.
2. მარცხენა მენიუდან გახსენით API პარამეტრები განყოფილება. From the left menu open the API Settings section.
3. დააკოპირეთ ან გენერირება გააკეთეთ ახალი API key. Copy your existing key or generate a new API key.
4. გამოიყენეთ key ყველა API მოთხოვნაში — query პარამეტრად ან request body-ში. Use the key in all API requests — as a query parameter or in the request body.

Base URL

Base URL

Authentication

Authentication

# Query parameter
curl "https://api.gosms.ge/api/sendsms?api_key=YOUR_KEY&to=995555123456&text=Hello"

# Request body (POST)
curl -X POST "https://api.gosms.ge/api/sendsms" \
  -d "api_key=YOUR_KEY&to=995555123456&text=Hello"

SMS გაგზავნა Send SMS

პარამეტრებიParameters

{
  "success": true,
  "messageId": 1,
  "from": "GOSMS.GE",
  "to": "995123456789",
  "text": "სატესტო სმს შეტყობინება",
  "sendAt": "2020-05-23T08:36:57.255Z",
  "balance": 94,
  "encode": "unicode",
  "segment": 1,
  "smsCharacters": 23
}

Bulk SMS გაგზავნა Send Bulk SMS

შეზღუდვა: მაქსიმუმ 1000 მიმღები ერთ მოთხოვნაში.

Limit: Maximum 1000 recipients per request.

პარამეტრებიParameters

// Request
{
  "api_key": "your_api_key",
  "from": "GOSMS.GE",
  "to": ["995555123456", "995598123456", "995599000000"],
  "text": "სატესტო სმს შეტყობინება",
  "urgent": false,
  "noSmsNumber": ""
}

// Response
{
  "success": true,
  "totalCount": 3,
  "successCount": 2,
  "failedCount": 1,
  "balance": 92,
  "messages": [
    { "messageId": 123, "to": "995555123456", "success": true },
    { "messageId": 124, "to": "995598123456", "success": true },
    { "messageId": 0,   "to": "995599000000", "success": false, "error": "Invalid phone number format" }
  ]
}

SMS სტატუსის შემოწმება Check SMS Status

პარამეტრებიParameters

{
  "success": true,
  "messageId": 1,
  "from": "GOSMS.GE",
  "to": "995123456789",
  "text": "სატესტო სმს შეტყობინება",
  "sendAt": "2020-05-23T08:36:57.255Z",
  "encode": "unicode",
  "segment": 1,
  "smsCharacters": 23,
  "status": "DELIVERED"
}

OTP SMS

OTP გაგზავნაSend OTP

OTP (ერთჯერადი დროებითი პაროლი) გაგზავნამდე API key-ს სისტემაში გაუწერეთ: ბრენდ სახელი, აპლიკაციის სახელი, hash კოდი და კოდის მოქმედების ვადა. პაროლი სისტემაში არ ინახება.

Before using OTP, configure your API key with: Sender name, Application name, App hash, and Code validity period. The password is not stored in the system.

პარამეტრებიParameters

{
  "success": true,
  "hash": "hashkey",
  "to": "995123456789",
  "sendAt": "2020-05-24T09:56:02.449Z",
  "encode": "default",
  "segment": 1,
  "smsCharacters": 57
}

Response Headers — Rate Limit

OTP შემოწმებაVerify OTP

{ "success": true, "verify": true }

SMS ბალანსის შემოწმება Check SMS Balance

პარამეტრებიParameters

{ "success": true, "balance": 94 }

ბრენდ სახელის შექმნა Create Sender Name

პარამეტრებიParameters

{ "success": true }

SDK ბიბლიოთეკები SDK Libraries

ოფიციალური SDK ბიბლიოთეკები GOSMS.GE API-ს სწრაფი ინტეგრაციისთვის.

Official SDK libraries for quick GOSMS.GE integration.

const { SMS } = require('@gosmsge/gosmsge-node');
const sms = new SMS('your_api_key');

// Send SMS
sms.send('995555555555', 'Hello!', 'GOSMS.GE')
   .then(r => console.log('ID:', r.messageId, '| Balance:', r.balance));

// Send Bulk SMS
sms.sendBulk('GOSMS.GE', ['995555111111', '995555222222'], 'Hello!')
   .then(r => console.log(`Sent: ${r.successCount}/${r.totalCount}`));

// Check balance
sms.balance().then(r => console.log('Balance:', r.balance));

from gosms import SMS

sms = SMS("your_api_key")

# Send SMS
result = sms.send("995555555555", "Hello!", "GOSMS.GE")
print(result.message_id, result.balance)

# Send Bulk SMS
result = sms.send_bulk("GOSMS.GE", ["995555111111", "995555222222"], "Hello!")
print(f"Sent: {result.success_count}/{result.total_count}")

# Async (pip install gosms-python[async])
# async with AsyncSMS("your_api_key") as sms:
#     result = await sms.send("995555555555", "Hello!", "GOSMS.GE")

use GoSmsGe\SmsSDK\GoSmsClient;

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

// Send SMS
$r = $client->sendSms('GOSMS.GE', '995555555555', 'Hello!');
echo $r->messageId . ' | Balance: ' . $r->balance;

// Send Bulk SMS
$r = $client->sendBulkSms('GOSMS.GE', ['995555111111', '995555222222'], 'Hello!');
echo "Sent: {$r->successCount}/{$r->totalCount}";

// Check balance
echo $client->checkBalance()->balance;

// DI registration (Program.cs)
builder.Services.AddGoSmsClient(options =>
{
    options.ApiKey = "your_api_key";
    options.Sender = "GOSMS.GE";
});

// Or standalone
var sms = new GoSmsClient(httpClient, options);

// Send SMS
var r = await sms.SendAsync("995555555555", "Hello!");
Console.WriteLine($"ID: {r.MessageId} | Balance: {r.Balance}");

// Send Bulk SMS
var bulk = await sms.SendBulkAsync(new[] { "995555111111", "995555222222" }, "Hello!");
Console.WriteLine($"Sent: {bulk.SuccessCount}/{bulk.TotalCount}");

Webhooks

Webhook-ები საშუალებას გაძლევთ მიიღოთ რეალურ დროში შეტყობინებები SMS სტატუსის ცვლილებებზე და შემომავალ შეტყობინებებზე. GOSMS.GE გამოგიგზავნის HTTP POST მოთხოვნას თქვენს endpoint-ზე ყოველ ჯერზე, როდესაც მოხდება შეტყობინება.

Webhooks let you receive real-time notifications for SMS delivery status changes and inbound (MO) messages. GOSMS.GE sends an HTTP POST to your endpoint each time an event occurs.

კონფიგურაცია: დააყენეთ Webhook URL მიწოდების სტატუსის შეტყობინებებისთვის და DLR URL შემომავალი SMS-ებისთვის — ორივე პარამეტრი ხელმისაწვდომია admin panel-ის API პარამეტრების განყოფილებაში.

Configuration: Set Webhook URL for delivery status notifications and DLR URL for inbound SMS — both are configured in the API settings section of the admin panel.

ივენთის ტიპები

Event types

Payload — delivery_status

Payload — delivery_status

{
  "eventId":   "a3f2c1d4-5e6b-7890-abcd-ef1234567890",
  "event":     "delivery_status",
  "timestamp": "2026-07-26T14:00:00Z",
  "messageId": 605647127,
  "from":      "GOSMS.GE",
  "to":        "995555123456",
  "status":    "DELIVERED",
  "text":      "Hello from GOSMS!",
  "sendAt":    "2026-07-26T13:59:00Z"
}

Payload — inbound (MO)

Payload — inbound (MO)

{
  "eventId":   "b7e9d2f1-3a4c-5678-bcde-fa0987654321",
  "event":     "inbound",
  "timestamp": "2026-07-26T14:05:00Z",
  "from":      "995555987654",
  "to":        "995322123456",
  "text":      "Reply from subscriber",
  "sendAt":    "2026-07-26T14:05:00Z"
}

HTTP Headers

HTTP Headers

ხელმოწერის გადამოწმება

Signature verification

X-Webhook-Signature header-ის ფორმატია t=<unix_ts>,v1=<hex_hmac>. ხელმოწერა გამოითვლება შემდეგნაირად: HMAC-SHA256(secret, "unix_ts.request_body").

The X-Webhook-Signature header has the format t=<unix_ts>,v1=<hex_hmac>. The signature is computed as HMAC-SHA256(secret, "unix_ts.request_body").

import hmac, hashlib

def verify_webhook(secret, header, body):
    parts = dict(p.split("=", 1) for p in header.split(","))
    ts  = parts["t"]
    sig = parts["v1"]
    expected = hmac.new(
        secret.encode(),
        (ts + ".").encode() + body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, sig)

const crypto = require('crypto');

function verifyWebhook(secret, header, body) {
  const parts = Object.fromEntries(
    header.split(',').map(p => p.split('='))
  );
  const ts  = parts['t'];
  const sig = parts['v1'];
  const expected = crypto
    .createHmac('sha256', secret)
    .update(ts + '.' + body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(sig)
  );
}

function verifyWebhook(string $secret, string $header, string $body): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $ts       = $parts['t'];
    $sig      = $parts['v1'];
    $expected = hash_hmac('sha256', $ts . '.' . $body, $secret);
    return hash_equals($expected, $sig);
}

Retry პოლიტიკა

Retry policy

GOSMS.GE იყენებს durable outbox-ს — ყოველი ივენთი ინახება მონაცემთა ბაზაში გაგზავნამდე. თუ თქვენი endpoint-ი 2xx კოდის ნაცვლად სხვა პასუხს დაბრუნებს, სისტემა ავტომატურად გამოიმეორებს მოთხოვნას exponential backoff-ით. Redirect-ები არ მიჰყვება.

GOSMS.GE uses a durable outbox — every event is persisted before dispatch. If your endpoint returns a non-2xx status, the system retries automatically with exponential backoff. Redirects are not followed. Your endpoint must return HTTP 2xx to acknowledge receipt.

შეცდომები Errors

API იყენებს მხოლოდ ორ HTTP სტატუს კოდს:

The API uses only two HTTP status codes:

შეცდომების კოდებიError Codes