GoSMSCore 6.1.1

GoSMSCore — .NET SDK for GOSMS.GE

.NET client library to send SMS messages using the GOSMS.GE SMS Gateway.

Targets: .NET Standard 2.0 (Framework 4.6.1+, .NET Core 2.0+) and .NET 8.0

To use this library, you must have a valid account on https://gosms.ge.

Please note SMS messages sent with this library will be deducted from your GOSMS.GE account credits.

For any questions, please contact us at info@gosms.ge

Installation

dotnet add package GoSMSCore

Or via the NuGet Package Manager:

Install-Package GoSMSCore

Quick Start

With Dependency Injection (recommended)

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

// In your service or controller
public class SmsNotificationService
{
    private readonly IGoSmsClient _sms;

    public SmsNotificationService(IGoSmsClient sms)
    {
        _sms = sms;
    }

    public async Task SendWelcomeMessage(string phone)
    {
        var result = await _sms.SendAsync(phone, "Welcome to our service!");
        Console.WriteLine($"Message ID: {result.MessageId}, Balance: {result.Balance}");
    }
}

Without Dependency Injection

using GoSMSCore;
using Microsoft.Extensions.Options;

var options = Options.Create(new GoSmsClientOptions
{
    ApiKey = "your_api_key",
    Sender = "GOSMS.GE"
});

var httpClient = new HttpClient { BaseAddress = new Uri("https://api.gosms.ge/api") };
var sms = new GoSmsClient(httpClient, options);

var result = await sms.SendAsync("995555555555", "Hello!");
Console.WriteLine($"Message ID: {result.MessageId}");

Usage

Send SMS

var result = await sms.SendAsync("995555555555", "Hello!");
Console.WriteLine($"Message ID: {result.MessageId}");
Console.WriteLine($"Balance: {result.Balance}");

// Send urgent message
var urgent = await sms.SendAsync("995555555555", "Urgent alert!", urgent: true);

Send Bulk SMS

var phones = new[] { "995555111111", "995555222222", "995555333333" };
var result = await sms.SendBulkAsync(phones, "Hello everyone!");

Console.WriteLine($"Sent: {result.SuccessCount}/{result.TotalCount}");
foreach (var msg in result.Messages!)
{
    if (!msg.Success)
        Console.WriteLine($"Failed: {msg.To} - {msg.Error}");
}

// With noSmsNumber for advertising campaigns
var adResult = await sms.SendBulkAsync(phones, "Special offer!", noSmsNumber: "995322000000");

Send OTP

var otpResult = await sms.SendOtpAsync("995555555555");
Console.WriteLine($"Hash: {otpResult.Hash}"); // Save this for verification
Console.WriteLine($"Balance: {otpResult.Balance}");

Verify OTP

var verifyResult = await sms.VerifyOtpAsync("995555555555", "hash_from_sendOtp", "1234");
if (verifyResult.Verify)
    Console.WriteLine("OTP verified successfully");
else
    Console.WriteLine("Invalid OTP code");

Check Message Status

var status = await sms.CheckStatusAsync(12345);
Console.WriteLine($"Status: {status.Status}"); // e.g., "delivered", "pending", "failed"
Console.WriteLine($"From: {status.From}");
Console.WriteLine($"To: {status.To}");

Check Balance

var balance = await sms.CheckBalanceAsync();
Console.WriteLine($"Balance: {balance.Balance}");

Create Sender Name

var sender = await sms.CreateSenderAsync("MyCompany");
if (sender.Success)
    Console.WriteLine("Sender name created. Wait for approval before using it.");

Error Handling

The SDK throws GoSmsApiException for API errors with typed error codes:

using GoSMSCore;
using GoSMSCore.Exceptions;

try
{
    var result = await sms.SendAsync("995555555555", "Hello!");
}
catch (GoSmsApiException ex) when (ex.ErrorCode == GoSmsErrorCode.InsufficientBalance)
{
    Console.WriteLine("Not enough credits!");
}
catch (GoSmsApiException ex)
{
    Console.WriteLine($"API error {ex.ErrorCode}: {ex.ErrorMessage}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}

Configuration

builder.Services.AddGoSmsClient(options =>
{
    options.ApiKey = "your_api_key";       // Required
    options.Sender = "GOSMS.GE";           // Required - registered sender name
    options.BaseUrl = "https://api.gosms.ge/api"; // Optional (default)
    options.Timeout = TimeSpan.FromSeconds(30);   // Optional (default: 30s)
});

API Reference

IGoSmsClient Interface

All methods accept an optional CancellationToken parameter.

Response Types

SmsSendResponse

SendBulkSmsResponse

BulkSmsResult

OtpSendResponse

OtpVerifyResponse

CheckStatusResponse

BalanceResponse

SenderCreateResponse

Error Codes (GoSmsErrorCode)

Testing

dotnet test

The test suite uses xUnit and Moq to cover all 7 API endpoints, input validation, error handling, and request payload verification.

Versioning & Releases

This project follows Semantic Versioning with automated releases via GitHub Actions.

Commit Convention

We use Conventional Commits:

• feat: — New features (MINOR version bump)
• fix: — Bug fixes (PATCH version bump)
• chore:, docs:, refactor:, ci:, etc. — Other changes (PATCH version bump)
• BREAKING CHANGE: — Breaking changes (MAJOR version bump)

Automated Releases

Releases are automatically published when commits are pushed to main:

1. Build and test on .NET 8.0
2. Analyze commits for version bump type
3. Update version in .csproj
4. Generate CHANGELOG.md entry
5. Create git tag vX.Y.Z
6. Pack and publish to NuGet.org
7. Create GitHub release

Migration from v5.x

v6.0.0 is a full rewrite with breaking changes:

More Info

Visit our website: https://www.gosms.ge