Отправка SMS на Kotlin: API библиотеки sms-client-kotlin |…

Отправка SMS на Kotlin: API библиотеки sms-client-kotlin

Современные мобильные приложения и серверные решения часто требуют интеграции с SMS-шлюзами для отправки уведомлений, подтверждений или маркетинговых сообщений. Для языка Kotlin существует удобная библиотека sms-client-kotlin, которая предоставляет простой и типобезопасный API для работы с популярными SMS-провайдерами. В этой статье мы подробно разберём её архитектуру, методы и примеры использования.

Что такое sms-client-kotlin?

Библиотека sms-client-kotlin — это легковесный HTTP-клиент, написанный на чистом Kotlin с использованием корутин. Она абстрагирует работу с REST API различных SMS-провайдеров (например, Twilio, Vonage, SMS-Центр) и предоставляет единый интерфейс для отправки сообщений. Основные преимущества:

Асинхронность — все запросы выполняются через корутины Kotlin.
Типобезопасность — строгая типизация параметров запросов и ответов.
Модульность — поддержка нескольких провайдеров через единый интерфейс SmsSender.
Лёгкая настройка — минимальное количество зависимостей.

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

Для добавления библиотеки в проект используйте Gradle. Добавьте зависимость в файл build.gradle.kts:

dependencies {
    implementation("com.github.sms-client:sms-client-kotlin:1.2.0")
    implementation("io.ktor:ktor-client-core:2.3.0")
    implementation("io.ktor:ktor-client-cio:2.3.0") // или другой движок
}

После синхронизации проекта вы можете создать экземпляр клиента. Пример инициализации для провайдера Twilio:

import sms.client.SmsClient
import sms.client.provider.twilio.TwilioConfig

fun main() {
    val config = TwilioConfig(
        accountSid = "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        authToken = "your_auth_token_here",
        fromNumber = "+1234567890"
    )

    val client = SmsClient.create(config)
}

Основные методы API

Библиотека предоставляет несколько ключевых методов для отправки и управления SMS:

1. Отправка одного сообщения

Метод sendSms принимает номер получателя и текст сообщения. Возвращает объект SmsResult с информацией об отправке.

suspend fun sendSingleMessage(client: SmsClient) {
    val result = client.sendSms(
        to = "+79876543210",
        message = "Привет! Это тестовое сообщение из Kotlin."
    )

    when (result) {
        is SmsResult.Success -> println("Отправлено! ID: ${result.messageId}")
        is SmsResult.Failure -> println("Ошибка: ${result.errorMessage}")
    }
}

2. Пакетная отправка

Для массовой рассылки используйте метод sendBatch. Он принимает список получателей и общий текст (или индивидуальные сообщения).

suspend fun sendBatch(client: SmsClient) {
    val recipients = listOf(
        BatchRecipient("+79111111111", "Скидка 10% на первый заказ!"),
        BatchRecipient("+79222222222", "Ваш код подтверждения: 1234")
    )

    val batchResult = client.sendBatch(recipients)
    println("Успешно отправлено: ${batchResult.successCount}, ошибок: ${batchResult.failureCount}")
}

3. Проверка статуса доставки

Метод getDeliveryStatus позволяет получить актуальный статус ранее отправленного сообщения по его идентификатору.

suspend fun checkStatus(client: SmsClient, messageId: String) {
    val status = client.getDeliveryStatus(messageId)
    println("Статус сообщения $messageId: ${status.status} (${status.description})")
}

Обработка ошибок и исключений

Библиотека использует стандартные механизмы Kotlin для обработки ошибок. Все сетевые ошибки оборачиваются в исключения типа SmsException. Рекомендуется оборачивать вызовы в try-catch:

suspend fun safeSend(client: SmsClient) {
    try {
        val result = client.sendSms("+79998887766", "Тест")
        println(result)
    } catch (e: SmsException) {
        println("Сетевая ошибка: ${e.message}")
    } catch (e: IllegalArgumentException) {
        println("Некорректный номер: ${e.message}")
    }
}