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

Променливи в съобщенията

Използвайте променливи, за да персонализирате каскадните съобщения с динамично съдържание като имена, URL адреси и персонализирани стойности.

Преглед

Променливите позволяват:

  • Персонализация: Вмъкване на имена на получатели, номера на акаунти
  • Динамични URL адреси: Включване на уникални връзки (линкове) за всеки получател
  • Съкращаване на URL: Автоматично съкращаване на дълги URL адреси
  • Многократна употреба на шаблони: Един шаблон, много персонализирани съобщения

Видове променливи

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

Синтаксис

Променливите използват формата: %type=id%

  • type: Тип на променливата (name, url, short_url)
  • id: Уникален идентификатор (integer)

Примери

Здравей %name=1%, твоят код е %name=2%
Посети нашия сайт: %url=1%
Бърза връзка: %short_url=1%

Използване на променливи

Стъпка 1: Качване на стойности за променливи

Преди да изпратите съобщения, качете стойностите на променливите в API:

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

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

Пълен пример

Качване на променливи

curl -X POST https://restapi.smsbat.com/api/items \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '{
    "variables": [
      {
        "id": 1,
        "type": "name",
        "value": "Сара"
      },
      {
        "id": 2,
        "type": "name",
        "value": "ORD-789"
      },
      {
        "id": 3,
        "type": "url",
        "value": "https://example.com/track/ORD-789"
      }
    ]
  }'

Изпращане на съобщение

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "order-notification",
      "fromName": "YourStore",
      "toPhone": "+380XXXXXXXXX",
      "messageType": "transaction",
      "text": "Здравей %name=1%! Поръчка %name=2% е изпратена. Проследете: %url=3%"
    }
  ]'

Доставено съобщение: 

Здравей Сара! Поръчка ORD-789 е изпратена. Проследете: https://example.com/track/ORD-789

Случаи на употреба

Потвърждение на поръчка

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "Иван"},
    {"id": 2, "type": "name", "value": "12345"},
    {"id": 3, "type": "name", "value": "$99.99"},
    {"id": 4, "type": "url", "value": "https://store.com/order/12345"}
  ]
}

// Message
{
  "text": "Здравей %name=1%! Поръчка #%name=2% за %name=3% е потвърдена. Подробности: %url=4%"
}

// Result
"Здравей Иван! Поръчка #12345 за $99.99 е потвърдена. Подробности: https://store.com/order/12345"

Възстановяване на парола

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "Майк"},
    {"id": 2, "type": "short_url", "value": "https://app.example.com/reset?token=abc123def456"}
  ]
}

// Message
{
  "text": "Здравей %name=1%, смени паролата си тук: %short_url=2% (валидно 30 мин)"
}

// Result
"Здравей Майк, смени паролата си тук: https://sho.rt/xyz789 (валидно 30 мин)"

Промоционална кампания

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "VIP20"},
    {"id": 2, "type": "short_url", "value": "https://store.com/sale?utm_source=sms&utm_campaign=summer"}
  ]
}

// Message
{
  "text": "Лятна Разпродажба! Използвай код %name=1% за 20% отстъпка: %short_url=2%"
}

// Result
"Лятна Разпродажба! Използвай код VIP20 за 20% отстъпка: https://sho.rt/abc"

Верификация на акаунт

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "789456"},
    {"id": 2, "type": "name", "value": "10"}
  ]
}

// Message
{
  "text": "Вашият код за потвърждение е: %name=1%. Валиден за %name=2% минути."
}

// Result
"Вашият код за потвърждение е: 789456. Валиден за 10 минути."

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

ID-та на променливи

  • ✅ Използвайте последователни идентификатори (1, 2, 3, ...)
  • ✅ Използвайте повторно идентификатори за масови съобщения с едни и същи променливи
  • ✅ Документирайте картографирането на ID на променливи
  • ❌ Не използвайте произволни идентификатори
  • ❌ Не прескачайте номера на идентификатори

Стойности на променливите

  • ✅ Валидирайте стойностите преди качване
  • ✅ Обработвайте правилно специалните символи
  • ✅ Тествайте с гранични случаи (edge cases)
  • ❌ Не включвайте HTML в променливи
  • ❌ Не превишавайте разумните ограничения за дължина

URL променливи

  • ✅ Използвайте short_url за дълги URL адреси
  • ✅ Включете параметри за проследяване (UTM)
  • ✅ Използвайте HTTPS
  • ❌ Не използвайте подозрителни URL адреси
  • ❌ Не включвайте чувствителни данни (напр. пароли) в URL адресите

Производителност

  • Качвайте променливи групово (на партиди)
  • Кеширайте често използвани променливи по идентификатор
  • Почиствайте периодично старите променливи

Отстраняване на проблеми

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

  • Уверете се, че променливите са качени преди изпращане
  • Проверете дали ID на променливата съвпада в текста и при качване
  • Осигурете правилен синтаксис: %type=id%
  • Потвърдете, че типът на променливата съответства на стойността

Съкращаването на URL е неуспешно

  • Проверете дали URL адресът е валиден и достъпен
  • Уверете се, че URL адресът започва с http:// или https://
  • Уверете се, че URL адресът все още не е бил съкратен

Превишен лимит за променливи

  • Свържете се с поддръжката за лимитите на променливи
  • Използвайте повторно идентификатори на променливи, когато е възможно
  • Почиствайте стари променливи

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