Отправка SMS на Kotlin: API библиотеки для интеграции

Отправка SMS на Kotlin: API библиотеки для быстрой интеграции

В современной веб-разработке возможность программно отправлять SMS-сообщения остаётся востребованной функцией — от двухфакторной аутентификации до уведомлений о статусе заказа. Если вы используете Kotlin для серверной части (Ktor, Spring Boot) или мобильного приложения (Android), вам потребуется надёжный инструмент для работы с SMS-провайдерами. В этой статье мы рассмотрим API библиотеку для отправки SMS на Kotlin, её возможности, примеры интеграции и лучшие практики.

Что такое API библиотека для отправки SMS?

API библиотека — это набор классов и функций, который абстрагирует работу с HTTP-запросами к серверу SMS-провайдера. Вместо того чтобы вручную формировать URL, заголовки и парсить JSON, вы вызываете простые методы Kotlin: sendSms(phone, message). Библиотека берёт на себя аутентификацию, сериализацию, повторные попытки при ошибках сети и обработку ответов.

Основные возможности библиотеки

• Простая отправка SMS — указание номера получателя, текста и опционально имени отправителя (альфа-имя).
• Пакетная рассылка — отправка одного сообщения на список номеров.
• Проверка статуса — получение информации о доставке (доставлено, в очереди, ошибка).
• Поддержка разных провайдеров — Twilio, Vonage (Nexmo), SMSC.ru, Smsc.ua и других.
• Асинхронность — все методы возвращают suspend функции или Deferred для корутин.
• Логирование и обработка ошибок — встроенные механизмы для отладки.

Установка и подключение

Библиотека распространяется через Maven Central или JitPack. Добавьте зависимость в build.gradle.kts:

// build.gradle.kts (для Gradle Kotlin DSL)
dependencies {
    implementation("com.example:sms-api:1.0.0")
    // если используете Ktor Client
    implementation("io.ktor:ktor-client-core:2.3.0")
    implementation("io.ktor:ktor-client-okhttp:2.3.0")
}

Для Android добавьте также разрешение на интернет в AndroidManifest.xml.

Базовый пример отправки SMS

Рассмотрим минимальный пример отправки одного сообщения через провайдер SMSC.ru (аналогично для других).

import com.example.smsapi.SmsClient
import com.example.smsapi.model.SmsRequest
import com.example.smsapi.model.SmsResponse

suspend fun sendSingleSms() {
    // Создаём клиент с учётными данными
    val client = SmsClient.create(
        login = "your_login",
        password = "your_password",
        provider = SmsProvider.SMSC
    )

    // Формируем запрос
    val request = SmsRequest(
        phone = "+71234567890",
        message = "Ваш код подтверждения: 1234",
        sender = "MyApp" // альфа-имя, если поддерживается
    )

    // Отправляем и получаем ответ
    val response: SmsResponse = client.send(request)

    when (response.status) {
        SmsStatus.SUCCESS -> println("SMS отправлено, ID: ${response.id}")
        SmsStatus.ERROR -> println("Ошибка: ${response.errorMessage}")
        else -> println("Неизвестный статус")
    }
}

Пакетная рассылка

Для отправки одного сообщения на несколько номеров используйте метод sendBatch:

val phones = listOf("+71234567890", "+70987654321", "+71112223344")
val batchRequest = BatchSmsRequest(
    phones = phones,
    message = "Уважаемые клиенты, акция продлена до пятницы!",
    sender = "ShopBot"
)

val batchResponse = client.sendBatch(batchRequest)
batchResponse.results.forEach { result ->
    println("Телефон: ${result.phone}, статус: ${result.status}")
}

Асинхронная обработка с корутинами

Библиотека полностью поддерживает корутины Kotlin. Вы можете запускать отправку в фоновом потоке:

import kotlinx.coroutines.*

fun main() = runBlocking {
    val job = launch(Dispatchers.IO) {
        sendSingleSms()
    }
    job.join()
    println("Готово")
}

Обработка ошибок и повторные попытки

Библиотека предоставляет встроенный механизм retry. Вы можете настроить количество попыток и задержку:

val client = SmsClient.create(
    login = "login",
    password = "pass",
    provider = SmsProvider.TWILIO,
    config = ClientConfig(
        retryCount = 3,
        retryDelayMs = 1000L