Към съдържанието

Изпращане на съобщение (Send Message)

Изпращайте съобщения чрез SMSBAT API използвайки крайната точка /bat/messagelist.

Крайна точка (Endpoint)

POST /bat/messagelist

Структура на заявката

Тялото на заявката е JSON масив от обекти на съобщения:

{
  "messages": [
    {
      "from": "ВашиятПодател",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Текстът на вашето съобщение",
      "customerMessageId": "your-internal-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 Специфична за типа конфигурация (варира според типа съобщение)

Автентикация

Изберете един от трите метода за удостоверяване:

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -H "X-Authorization-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "ВашиятПодател",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Здравейте от SMSBAT!"
    }]
  }'

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

curl -X POST https://restapi.smsbat.com/bat/messagelist \
  -u "@:your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{
      "from": "ВашиятПодател",
      "to": "+380XXXXXXXXX",
      "type": "sms",
      "text": "Здравейте от SMSBAT!"
    }]
  }'

Отговор (Response)

Отговор при успех

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 1,
      "customerMessageId": "your-internal-id",
      "to": "+380XXXXXXXXX"
    }
  ]
}

Полета в отговора

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

Типове съобщения

SMS

Обикновени текстови съобщения:

{
  "from": "ВашиятПодател",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Текстът на вашия SMS"
}

Viber Promo

Промоционални съобщения с мултимедийно съдържание:

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

Viber Transactional

Транзакционни известия:

{
  "from": "ВашиятПодател",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Вашата поръчка #12345 беше потвърдена"
}

Viber OTP

Известия за еднократна парола (OTP):

{
  "from": "ВашиятПодател",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "code": "123456",
    "validity": 300
  }
}

Обработка на грешки

HTTP кодове за статус

Код Описание
200 Заявката е успешна
400 Лоша заявка - невалидни параметри
401 Неоторизиран - неуспешно удостоверяване
429 Твърде много заявки - ограничението за скорост е надвишено
500 Вътрешна грешка в сървъра

Отговор при грешка

{
  "error": {
    "code": "INVALID_RECIPIENT",
    "message": "Невалиден формат на телефонния номер"
  }
}

Добри практики

Формат на телефонния номер

Винаги използвайте E.164 формат за телефонни номера:

  • ✅ Правилно: +380XXXXXXXXX
  • ❌ Неправилно: 380XXXXXXXXX, 0XXXXXXXXX

Текст на съобщението

  • Поддържайте SMS съобщенията под 160 знака, за да избегнете разделяне на няколко части
  • Използвайте UTF-8 кодиране за международни символи
  • Тествайте специалните символи преди масово изпращане

TTL (Time-to-Live / Време на живот)

  • Задайте подходящо TTL за съобщения, чувствителни към времето
  • OTP съобщения: 300-600 секунди (5-10 минути)
  • Промоционални съобщения: 3600-86400 секунди (1-24 часа)

Идентификатор на съобщението на клиента (Customer Message ID)

  • Използвайте уникални идентификатори за всяко съобщение
  • Помага при проследяване и отстраняване на грешки
  • Полезно за корелация със записите на вашата система

Ограничения на скоростта (Rate Limits)

Свържете се с вашия акаунт мениджър за информация относно:

  • Съобщения в секунда
  • Съобщения на ден
  • Едновременни (concurrent) връзки

Следващи стъпки