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

Изпращане на съобщение (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	Специфична за типа конфигурация (варира според типа съобщение)

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

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

=== “API Key Header”

```bash
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!"
    }]
  }'
```

=== “HTTP Basic Auth”

```bash
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!"
    }]
  }'
```

=== “API Key като Парола”

```bash
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"
}

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

{
  "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) връзки

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

Viber съобщения - Разгледайте Viber типове съобщения
SMS съобщения - Научете повече за SMS
Проверете статуса - Проследете доставката на съобщения

Search Results