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

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

Надсилайте повідомлення через 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 повідомлення"
}

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

{
  "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)

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

Повідомлення Viber - Детально про формати Viber
SMS - Детальніше про SMS повідомлення
Отримання статусів - Відстеження статусів доставки

Search Results