Перейти до змісту

Надсилання Повідомлень

Надсилайте повідомлення через SMSBAT API за допомогою ендпоінту /bat/messagelist.

Ендпоінт

POST /bat/messagelist

Структура Запиту

Тіло запиту повинно містити масив messages з об'єктами повідомлень:

{
  "messages": [
    {
      "from": "ВашВідправник",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Текст вашого повідомлення",
      "customerMessageId": "ваш-внутрішній-id",
      "ttl": 3600
    }
  ]
}

Параметри

Обов'язкові Параметри

Параметр Тип Опис
from string Альфа-ім'я відправника (Sender ID)
to string Телефон отримувача у форматі E.164 (напр., +380XXXXXXXXX)
type string Тип повідомлення: sms, viber_promo, viber_trans, viber_carousel, viber_survey, viber_otp, rcs, flashcall
text string Текст повідомлення (обов'язковий для більшості типів, опціональний для інших)

Опціональні Параметри

Параметр Тип Опис
customerMessageId string Ваш внутрішній ідентифікатор для трекінгу (ідентифікатор кореляції)
ttl integer Час життя повідомлення (Time-to-Live) у секундах
messageData object Специфічні налаштування даних в залежності від type повідомлення

Авторизація

Оберіть один із трьох доступних методів авторизації:

Метод 1: Заголовок з API Ключем

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: ваш-api-ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Привіт від SMSBAT!"
    }]
  }'

Метод 2: HTTP Basic Auth

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "username:password" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Привіт від SMSBAT!"
    }]
  }'

Метод 3: API Ключ замість Пароля

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:ваш-api-ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "YourSender",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Привіт від SMSBAT!"
    }]
  }'

Відповідь (Response)

Успішна Відповідь

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "ваш-внутрішній-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Поля Відповіді

Поле Тип Опис
messagelistId integer Унікальний ідентифікатор всього пакету повідомлень (усієї розсилки)
messageId string Унікальний ідентифікатор кожного окремого повідомлення
status string Статус прийняття до обробки: accepted, rejected, failed
parts integer Кількість сегментів повідомлення (для SMS)
customerMessageId string Ваш внутрішній ідентифікатор (якщо він був переданий)
to string Номер телефону отримувача

Типи Повідомлень (Приклади)

SMS

Звичайні текстові повідомлення:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Текст вашого SMS повідомлення"
}

Viber Promo

Маркетингові повідомлення з медіа:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Погляньте на наш новий продукт!",
  "messageData": {
    "image": "https://example.com/image.jpg",
    "button": {
      "text": "Переглянути",
      "url": "https://example.com/product"
    }
  }
}

Viber Transactional

Транзакційні повідомлення:

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Ваше замовлення #12345 підтверджено"
}

Viber OTP

Повідомлення з одноразовим паролем (OTP):

{
  "from": "YourSender",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Обробка помилок

HTTP Статуси

Код Опис
200 Запит успішний
400 Некоректний запит — помилка у параметрах під час інтеграції
401 Не авторизовано — помилка авторизації чи ключа
429 Забагато запитів — перевищено ліміт запитів (Rate Limit)
500 Внутрішня помилка сервера

Структура Помилки

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Invalid phone number format"
  }
}

Кращі Практики

Формат Номера Телефону

Слід завжди використовувати формат E.164: - ✅ Правильно: +380XXXXXXXXX - ❌ Неправильно: 380XXXXXXXXX, 0XXXXXXXXX

Текст повідомлення

  • Намагайтеся зберегти довжину SMS до 160 (або 70 кириличних) символів, щоб обійтися одним сегментом.
  • Використовуйте кодування UTF-8.
  • Перевіряйте спецсимволи (наприклад ~, ^, |) перед масовою розсилкою.

Час життя повідомлення (TTL)

  • Вказуйте доцільний TTL для термінових повідомлень.
  • OTP (коди): 300–600 секунд (5–10 хвилин)
  • Маркетинг (Promo): 3600–86400 секунд (1–24 години)

Трекінговий ID (Customer Message ID)

  • Використовуйте свій унікальний customerMessageId для кожного запиту.
  • Допомагає синхронізувати звіти з вашою БД та вести дебаг.

Ліміти Запитів

Зверніться до свого персонального менеджера за детальною інформацією про ліміти на:

  • Кількість повідомлень за секунду (MPS)
  • Загальна квота розсилок на день
  • Кількість конвеєрів з'єднання (Concurrent connections)

Наступні Кроки