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

Змінні Повідомлень (Variables)

Використовуйте змінні для персоналізації каскадних повідомлень динамічним контентом: іменами, сумами, унікальними URL-адресами та індивідуальними значеннями.

Огляд

Змінні дозволяють:

  • Персоналізувати текст: Вставляти імена одержувачів, номери замовлень, промокоди.
  • Динамічні URL-адреси: Включати унікальні посилання для кожного одержувача.
  • Скорочення URL-адрес: Автоматично скорочувати довгі посилання.
  • Багаторазове використання шаблонів: Один сталий шаблон, але багато персоналізованих повідомлень.

Типи змінних

Тип Синтаксис Призначення Приклад
name %name=id% Текстові змінні Імена, коди, суми
url %url=id% Повні URL-адреси Посилання, індивідуальні трекери
short_url %short_url=id% Скорочені URL-адреси Компактні посилання

Синтаксис Змінних

Змінні в тексті повідомлення завжди мають такий формат: %type=id%

  • type: Тип змінної (name, url або short_url).
  • id: Унікальний числовий ідентифікатор змінної.

Приклади використання у тексті:

Привіт, %name=1%, твій одноразовий код: %name=2%
Відвідай наш сайт: %url=1%
Коротке посилання: %short_url=1%

Використання Змінних

Крок 1: Завантажте значення змінних до API

Перш ніж надіслати повідомлення з плейсхолдерами, спочатку необхідно завантажити конкретні значення змінних до системи:

Ендпоінт: 

POST https://restapi.smsbat.com/api/items

Запит: 

{
  "variables": [
    {
      "id": 1,
      "type": "name",
      "value": "Іван"
    },
    {
      "id": 2,
      "type": "name",
      "value": "12345"
    },
    {
      "id": 3,
      "type": "url",
      "value": "https://example.com/products"
    },
    {
      "id": 4,
      "type": "short_url",
      "value": "https://example.com/very-long-url-that-needs-shortening"
    }
  ]
}

Крок 2: Надішліть повідомлення з прив'язаними змінними

Використовуйте ідентифікатори (ID) завантажених змінних безпосередньо у тексті повідомлення:

{
  "id": "msg-001",
  "fromName": "YourStore",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "transaction",
  "text": "Вітаємо, %name=1%! Ваш код верифікації %name=2%. Більше: %short_url=4%"
}

Результат на телефоні клієнта: 

Вітаємо, Іван! Ваш код верифікації 12345. Більше: https://sho.rt/abc123

Випадки використання

Підтвердження замовлення

// Відправлення змінних
{
  "variables": [
    {"id": 1, "type": "name", "value": "Іване"},
    {"id": 2, "type": "name", "value": "12345"},
    {"id": 3, "type": "name", "value": "1450.00 грн"},
    {"id": 4, "type": "url", "value": "https://store.com/order/12345"}
  ]
}

// Текст повідомлення
{
  "text": "Привіт, %name=1%! Замовлення #%name=2% на %name=3% успішно прийнято. Деталі: %url=4%"
}

// Результат:
"Привіт, Іване! Замовлення #12345 на 1450.00 грн успішно прийнято. Деталі: https://store.com/order/12345"

Відновлення пароля з унікальним лінком

// Відправлення змінних
{
  "variables": [
    {"id": 1, "type": "name", "value": "Марина"},
    {"id": 2, "type": "short_url", "value": "https://app.example.com/reset?token=abc123def456"}
  ]
}

// Текст повідомлення
{
  "text": "Привіт, %name=1%, для відновлення пароля перейдіть за посиланням: %short_url=2% (дійсне 30 хв)"
}

// Результат:
"Привіт, Марина, для відновлення пароля перейдіть за посиланням: https://sho.rt/xyz789 (дійсне 30 хв)"

Промо-кампанії

// Відправлення змінних
{
  "variables": [
    {"id": 1, "type": "name", "value": "VIP20"},
    {"id": 2, "type": "short_url", "value": "https://store.com/sale?utm_source=sms&utm_campaign=summer"}
  ]
}

// Текст повідомлення
{
  "text": "Літній розпродаж! Використай промокод %name=1% для -20% знижки: %short_url=2%"
}

// Результат:
"Літній розпродаж! Використай промокод VIP20 для -20% знижки: https://sho.rt/abc"

Практика

Значення id змінних

  • ✅ Використовуйте послідовні ID (1, 2, 3, ...).
  • ✅ Повторно використовуйте однакові ідентифікатори змінних для масового розсилання (економте ліміти).
  • ❌ Не використовуйте випадкові (random) ID.
  • ❌ Не пропускайте номери.

Форматування значень

  • ✅ Завжди валідуйте (перевіряйте) значення перед їх завантаженням.
  • ✅ Обробляйте спеціальні символи до відправки.
  • ❌ Ніколи не відправляйте HTML-теги або код у змінні типу name.

Довгі URL-адреси

  • ✅ Використовуйте short_url для візуального зменшення довгих посилань з UTM мітками.
  • ✅ Завжди використовуйте HTTPS.
  • ❌ Не скорочуйте підозрілі сайти, це може призвести до блокування Альфа-імені оператором.

Вирішення Проблем

Змінні не були замінені у тексті

  • Перевірте, чи ви завантажили змінні до того, як відправляти основне повідомлення.
  • Переконайтеся у збіжності ID у тексті повідомлення зі списком завантажених variables.
  • Перевірте правильний синтаксис: %type=id%.

URL не скоротився

  • Перевірте, чи URL має правильний стандартний вигляд (доступний у браузері, починається з http:// або https://).
  • Спробуйте використати звичайний url замість short_url.

Перевищено ліміт на змінні

  • Реюз (reuse) змінних є нормальною практикою. Якщо у вас в розсилці на тисячі повідомлень однакове посилання — створіть її один раз із id: 1 і використайте в усіх повідомленнях.

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