SMS Съобщения

Изпращайте стандартни текстови съобщения с помощта на SMSBAT API. SMS е най-универсалният канал за съобщения с най-високи проценти на доставка във всички мобилни устройства.

Преглед

SMS (услуга за кратки съобщения) е идеален за:

Известия, критични за времето
Резервен канал (fallback) за съобщения във Viber/RCS
Достигане до потребители без смартфони
Универсална съвместимост във всички мобилни мрежи
Високи коефициенти на доставка (95%+)

Базово SMS Съобщение

Заявка

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

Параметри

Параметър	Тип	Задължителен	Описание
`from`	string	Да	Алфанумеричен идентификатор на подателя (Sender ID - до 11 знака)
`to`	string	Да	Телефонен номер на получателя във формат E.164
`type`	string	Да	Задайте на `"sms"`
`text`	string	Да	Съдържание на съобщението
`customerMessageId`	string	Не	Вашият вътрешен ID за проследяване
`ttl`	integer	Не	Време на живот (Time-to-live) в секунди

Примери

Прост SMS

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": "Здравейте! Това е тестово SMS съобщение."
    }]
  }'

SMS с Идентификатор (ID) на клиента

{
  "messages": [{
    "from": "ВашиятМагазин",
    "to": "+380XXXXXXXXX",
    "type": "sms",
    "text": "Вашата поръчка #12345 е изпратена.",
    "customerMessageId": "order-12345-notification"
  }]
}

SMS с TTL

{
  "messages": [{
    "from": "ВашетоПриложение",
    "to": "+380XXXXXXXXX",
    "type": "sms",
    "text": "Вашият код за потвърждение е: 123456",
    "ttl": 300
  }]
}

Кодиране на символи

GSM 7-bit Кодиране

Стандартна GSM азбука (160 знака на SMS):

A-Z a-z 0-9
@ £ $ ¥ è é ù ì ò Ç Ø ø Å å
Δ _ Φ Γ Λ Ω Π Ψ Σ Θ Ξ
! " # % & ' ( ) * + , - . / : ; < = > ?

Разширени GSM символи

Тези символи се броят като 2 знака:

| ^ € { } [ ] ~ \

Unicode (UCS-2) Кодиране

Съобщенията със специални символи използват Unicode кодиране (70 знака на SMS):

Емоджита (Emoji): 😀 🎉 ❤️
Кирилица: А Б В Г Д Е Ж
Специални символи: ✓ ✗ ★ ♥

Дължина на съобщението

Единичен SMS

GSM 7-bit: 160 знака
Unicode: 70 знака

SMS, съставен от много части

Когато съобщението ви надвишава ограничението, то се разделя на няколко части:

GSM 7-bit: 153 знака на част
Unicode: 67 знака на част

Пример

{
  "messages": [{
    "from": "ВашатаМарка",
    "to": "+380XXXXXXXXX",
    "type": "sms",
    "text": "Това е много дълго съобщение, което ще бъде разделено на няколко части. Всяка част ще бъде доставена поотделно, но ще се появи като едно съобщение на телефона на получателя. Системата автоматично обработва разделянето и повторното сглобяване."
  }]
}

Това съобщение ще бъде разделено на множество части, особено когато съдържа кирилица (Unicode формат).

Отговор (Response)

Успешен отговор

{
  "messagelistId": 123456,
  "messages": [
    {
      "messageId": "abc123def456",
      "status": "accepted",
      "parts": 2,
      "customerMessageId": "order-12345-notification",
      "to": "+380XXXXXXXXX"
    }
  ]
}

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

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

Sender ID (Идентификатор на подателя)

Алфанумеричен подател

Използвайте името на вашата марка като подател (до 11 знака):

{
  "from": "ВашатаМарка",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Здравейте от ВашатаМарка!"
}

Ограничения:

Максимум 11 знака
Само букви и цифри
Без интервали или специални символи (кирилица НЕ се поддържа)
Получателят не може да отговаря на алфанумерични податели

Цифров подател

Използвайте телефонен номер като подател (за двупосочен SMS - two-way SMS):

{
  "from": "+380123456789",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Здравейте! Можете да отговорите на това съобщение."
}

Случаи на употреба (Use Cases)

OTP Удостоверяване (Verification)

{
  "from": "YourApp",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Вашият код за потвърждение е: 123456. Валиден за 5 минути.",
  "ttl": 300
}

Известия за поръчки

{
  "from": "YourStore",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Вашата поръчка #12345 е доставена. Благодарим ви, че пазарувате при нас!"
}

Напомняния за срещи

{
  "from": "YourClinic",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Напомняне: Вашият час е утре от 14:00 ч."
}

Потвърждения за плащане

{
  "from": "YourBank",
  "to": "+380XXXXXXXXX",
  "type": "sms",
  "text": "Плащането от 100 USD на търговец ABC е успешно. Идентификатор на транзакцията: 789xyz"
}

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

Съдържание на съобщението

✅ Поддържайте съобщенията кратки и ясни
✅ Включете идентификация на подателя
✅ Добавете призив за действие, ако е необходимо
✅ Използвайте правилна граматика и правопис
❌ Избягвайте прекомерна пунктуация!!!
❌ Не използвайте само ГЛАВНИ БУКВИ
❌ Избягвайте програми за съкращаване на URL адреси, които изглеждат подозрителни

Използване на знаци (Character Usage)

Проверете броя на знаците преди изпращане
Имайте предвид разширените GSM знаци (броят се за 2)
Тествайте със специални символи преди масово изпращане
Обмислете използването на GSM кодиране за по-дълги съобщения, ако е възможно

Телефонни номера

Винаги използвайте E.164 формат: +380XXXXXXXXX
Валидирайте телефонни номера преди изпращане
Премахнете невалидни номера от вашия списък
Поддържайте списъка си с контакти актуален

Време за изпращане (Timing)

Спазвайте местните часови зони
Избягвайте изпращане през нощта (от 22:00 до 8:00 ч.)
Обмислете работното време за търговски съобщения
Задайте подходящо TTL за чувствителни към времето съобщения

Съответствие с правила (Compliance)

Получете съгласие, преди да изпращате маркетингови съобщения
Включете инструкции за отказ (opt-out) за промоционални SMS
Спазвайте местните разпоредби (GDPR и др.)
Спазвайте списъците "Не безпокойте"

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

Често срещани грешки

Грешка	Причина	Решение
`INVALID_RECIPIENT`	Грешен телефонен формат	Използвайте E.164 формат
`INVALID_SENDER`	Невалиден ID на подателя	Проверете правилата за ID
`MESSAGE_TOO_LONG`	Превишава макс. дължина	Разделете или съкратете съобщението
`INVALID_ENCODING`	Неподдържани символи	Използвайте GSM или Unicode

Оптимизация на разходите

Намалете частите на съобщението

Пазете съобщенията под 160 знака (GSM) или 70 (Unicode)
Избягвайте специални символи, които задействат Unicode
Използвайте съкращения, когато е подходящо
Премахнете ненужните интервали

Примерна оптимизация

❌ Преди (173 знака, повече от 2 SMS-а, защото е Unicode):

Здравейте, Иван! Вашата поръчка #12345 е успешно доставена на вашия адрес на улица "Иван Вазов" 123. Благодарим ви, че пазарувате при нас! Надяваме се да се видим отново.

✅ След (114 знака, 2 SMS-а):

Здравейте, Иван! Поръчка #12345 е на ул. "Иван Вазов" 123. Благодарим Ви! Вижте details3.bg за пълната информация

Масово изпращане (Bulk Sending)

Изпращане на множество съобщения в една заявка:

{
  "messages": [
    {
      "from": "YourBrand",
      "to": "+380111111111",
      "type": "sms",
      "text": "Съобщение 1"
    },
    {
      "from": "YourBrand",
      "to": "+380222222222",
      "type": "sms",
      "text": "Съобщение 2"
    },
    {
      "from": "YourBrand",
      "to": "+380333333333",
      "type": "sms",
      "text": "Съобщение 3"
    }
  ]
}

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

Viber съобщения - Съобщения с мултимедийно съдържание
RCS съобщения - Rich Communication Services
Проверка на статус - Проследяване на състоянието на доставка
Резервни (Fallback) стратегии - Конфигуриране на fallbacks