Використання API-ресурсу Send prepared message

Ресурс Send prepared message призначений для відправлення підготовленого повідомлення одному або кільком контактам, в одному запиті можливо передати до тисячі одержувачів. Повідомлення можна параметризувати для кожного контакту окремо. Підтримується можливість працювати з email, SMS, Viber, Mob push і Web push-повідомленнями, вказуючи id в URL.

1. Опис запиту

Запит до ресурсу здійснюється POST-методом за адресою https://esputnik.com/api/v1/message/{id}/smartsend, де {id} — id (ідентифікатор) підготовленого в особистому кабінеті повідомлення.

{
"recipients" : [{
"contactId" : "Ідентифікатор контакту (може бути не вказаний, якщо вказано параметр locator).",
"locator" : "Одержувач. Наприклад, email-адреса для email-повідомлень, номер телефону для SMS або Viber.",
"jsonParam" : "Параметр у форматі json. Використовується для листів зі складними velocity-шаблонами.",
"languageCode" : "Бажана мова повідомлення для контакту. Використовується для мультимовних листів."
  }],
"email" : "Тип повідомлення. true - для email, false - для інших медіа-каналів.",
"fromName" : "Ім'я відправника. Потрібно вказати тільки ім'я відправника, без email-адреси. Буде використано email-адресу відправника, яку було вибрано в повідомленні. Для SMS вказується альфа-ім'я. Якщо параметр не вказано — буде використовуватися ім'я, вибране в повідомленні."
"externalRequestId" : "Необов'язковий параметр. Дозволяє надати відправленому повідомленню ваш власний ідентифікатор і потім за допомогою Get contacts activity отримати статус відправленого повідомлення."
}

2. Відповідь сервера

У відповідь від сервера при успішному запиті повертається результат відправлення одиночних повідомлень.

id — завжди повертається 0;

locator — email або номер телефону, на який відправлялося повідомлення;

{
    "id": 0,
    "results": [
        {
            "id": 0,
            "locator": "example@mail.com",
            "status": "OK",
            "requestId": "8b2e65d9-060b-4c61-bbd7-73c6796fa504"
        }, {
            "id": 0,
            "locator": "new. example@mail.com",
            "status": "OK",
            "requestId": "458f3533-51d9-439e-a5d0-5fb7c2490c41"
        }
    ]
}

Якщо запит здійснено успішно без помилок, відповідь від сервера при відправленні двох емейлів у межах одного запиту матиме приблизно такий вигляд:status — результат. OK — якщо повідомлення успішно додано до черги на відправлення; про статус повідомлення можна дізнатися, використовуючи requestId і запит до ресурсу.

ERROR — якщо повідомлення не вдалося додати до черги на відправлення.

message — опис помилки, повертається зі статусом ERROR.

Приклад: "message": "'example@mail.com' is not valid email"

3. Приклад використання з email-повідомленням

3.1. Відправлення повідомлення без параметризації

У тому випадку, коли ресурс використовується для відправлення одиночних email-повідомлень і немає потреби в додатковій параметризації для кожного одержувача окремо, більшість параметрів можна не використовувати.

Так, для відправлення одного листа тіло запиту набуває такого вигляду:

{
  "recipients": [
    {
      "jsonParam": null,
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

І для двох одержувачів відповідно:

{
  "recipients": [
    {
      "jsonParam": null,
      "locator": "example@mail.com"
    }, {
      "jsonParam": null,
      "locator": "new.example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

У випадку, коли поле fromName передається зі значенням null, у листі буде використовуватися ім'я, задане при додаванні адреси відправника:

Передача поля jsonParam зі значенням null свідчить про те, що в листі не планується або не передбачено використання динамічної параметризації.

Окрім null, jsonParam може містити JSON-об'єкти, вкладені об'єкти і вкладені масиви, які перед відправленням запиту потрібно серіалізувати, тобто послідовно перетворити об'єкти на JSON-рядок.

3.2. Передача JSON-об'єкта

Формат JSON-об'єкта встановлюється двома фігурними дужками { }, а дані з ключовими значеннями розміщені між ними. Між парами ключових значень знаходиться двокрапка: {"key" : "value"}. Кожна пара значень розділена комою, таким чином середина JSON має такий вигляд: {"key" : "value", "key" : "value", "key": "value"}.

Наприклад, об'єкт з двох пар ключових значень виглядатиме так:

{
  "discount": "5%",
  "link": "https://example.site.com/items_for_sale"
}

Для коректної передачі об'єкт у тілі запиту потрібно привести до рядка, і запит набуває такого вигляду:

{
  "recipients": [
    {
      "jsonParam": "{\"discount\":\"5%\",\"link\":\"https:\/\/site.com\/items_for_sale\"}",
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

Щоб вивести в повідомленні передані значення, слід скористатися velocity-конструкцією: $!data.get('discount') і $!data.get('link').

У редакторі повідомлень:

Так виглядатиме повідомлення в результаті підстановки даних:

Замість змінної discount буде підставлено ​​значення "5%", а для кнопки замість змінної link у ролі посилання буде підставлено ​​значення: "https://site.com/items_for_sale".

3.3. Передача вкладеного JSON-об'єкта

Формат вкладеного JSON-об'єкта "objectName": {"key" : "value", "key": "value"}. 

Приклад вкладених об'єктів customerData і orderData виглядатиме таким чином:

{
  "customerData": {
    "firstName": "Сергій",
    "lastName": "Іванов"
  },
    "orderData": {
    "name": "Смартфон Apple iPhone X 64GB Black",
    "cost": 25999,
    "url": "https:\\example.site.com\smartfon-apple-iphone-x-64gb.html",
    "imageUrl": "https:\\example.site.com\smartfon-apple\apple_iphone_x_64gb.jpg"
  }
}

Дані також треба привести до рядка (серіалізувати), і запит набуде вигляду:

{
  "recipients": [
    {
      "jsonParam": "{
\"customerData\":{\"firstName\":\"Сергій\",\"lastName\":\"Іванов\"},
\"orderData\":{\"name\":\"Смартфон Apple iPhone X 64GB Black\",
\"cost\":"25999",\"url\":\"https:\/\/example.site.com\/smartfon-apple-iphone-x-64gb.html\",
\"imageUrl\":\"https:\/\/example.site.com\/smartfon-apple\/apple_iphone_x_64gb.jpg\"}
}",
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

Для відображення даних у повідомленні використовуємо velocity-конструкцію такого вигляду:

$!data.get('customerData').get('firstName') и $!data.get('orderData').get('name') 

У редакторі повідомлень змінні для динамічного контенту:

У результаті підстановки даних одержувач побачить повідомлення так:

3.4. Передача вкладеного JSON-масиву

Масиви — впорядкована колекція значень; для визначення масиву використовуються квадратні дужки [ ], де значення розділяються комами.

Формат вкладеного JSON-масиву "arrayName": [{"key": "value", "key":"value"},{...}], у межах одного запиту може бути передано кілька масивів.

{
  "orderData": [
    {
      "name": "Смартфон Apple iPhone Xs 512Gb",
      "price": "49999",
      "url": "http://example.com/smartfon-apple-iphone-27.html",
      "imageUrl": "http://example.com/apple_iphone_xs_silver.jpg"
    },
    {...},
    {
      "name": "Смарт-годинник Apple Watch Series 4 GPS 44mm Space Grey",
      "price": "13699",
      "url": "http://example.com/smart-godynnyk-apple-watch-series-4-gps-45-2mm.html",
      "imageUrl": "http://example.com/apple_watch_series_4_gps_44mm.jpg"
    }],
  "recommendationsData": [
    {
      "name": "Захисне скло для смартфона MakeFuture 3D Apple iPhone X/XS",
      "url": "http://example.com/zahisne-sklo-dlja-smartfona-makefuture.html",
      "imageUrl": "http://example.com/makefuture_3d_apple_iphone_xxs_black.jpg",
      "price": "399"
    },
    {...},
    {
      "name": "Ремінець для смарт-годинника Apple 44mm Black Sport Band",
      "url": "http://example.com/reminets-dlja-smart-godynnyka-apple-44mm.html",
      "imageUrl": "http://example.com/apple_44mm_black_sport_band.jpg",
      "price": "1999"
    }
  ]
}

Важливо! Ідентично з об'єктом і вкладеним JSON-об'єктом JSON-масив треба також привести до рядка (серіалізувати).

Використовувати масиви краще під час роботи з великою кількістю даних, які можуть бути згруповані разом.

Щоб отримати доступ до даних із масиву, в повідомленні треба використовувати конструкцію вбудованого у velocity циклу foreach. На прикладі масиву orderData velocity-код набуває вигляду:

// Усередині цієї конструкції будуть послідовно виведені дані з кожного елемента масиву
#foreach($order in $!data.get('orderData'))
  // Для виведення значення із замовлення поля name
  $!order.get('name') 
  // Для поля url
  $!order.get('url') 
  // Для поля imageUrl
  $!order.get('imageUrl')
  // Для поля price
  $!order.get('price')  
#end 

Аналогічно для масиву, в якому передаються рекомендації

recommendationsData: 

// Усередині цієї конструкції будуть послідовно виведені дані з кожного елемента масиву
#foreach($recomm in $!data.get('recommendationsData'))
  $!recomm.get('name') 
  $!recomm.get('url') 
  $!recomm.get('imageUrl')
  $!recomm.get('price')  
#end 

Підготовлений лист з velocity-кодом матиме вигляд:

Результатом підстановки в лист даних про три товари із замовлення і три супутні рекомендації буде такий лист:

4. Приклад використання з SMS-повідомленням

Припустимо, є завдання додатково повідомити користувача SMS-повідомленням про те, що його замовлення сформовано й відправлено.

У такому разі формуємо тіло запиту такого вигляду:

{
  "recipients": [
    {
      "jsonParam": "{\"firstName\":\"Сергій\",\"orderId\":\"JN134173389\",\"deliveryAddress\":\"м. Дніпро, відділення НП №32\"}",
      "locator": "380501234567"
    }
  ],
  "email": false,
  "fromName": "V-COMP"
}

де в полі locator вказуємо номер телефону одержувача, а у fromName — альфа-ім'я.

Підготуємо SMS-повідомлення в особистому кабінеті:

Так повідомлення виглядатиме з підстановкою даних:

У тілі SMS-повідомлення не завжди раціонально виводити весь контент масиву за допомогою циклу foreach, тож можна звернутися до конкретного елементу масиву; на прикладі orderData velocity конструкція набуває вигляду: $!data.get('orderData').get(0).get('name'), де відбувається звернення до першого елементу масиву (нумерація з 0).

5. Приклад використання з Viber-повідомленням

Процес налаштування ідентичний налаштуванню SMS. Треба визначитися з тими даними, які ви плануєте відобразити у Viber-повідомленні. Але слід урахувати, що Viber-повідомлення, на відміну від SMS, може вмістити до 1000 символів, а також відобразити зображення та кнопку, до якої можна додати посилання.

У цьому випадку тіло запиту набуває вигляду:

{
    "recipients": [
        {
            "jsonParam": "{
\"firstName\":\"Сергій\",\"orderId\":\"JN134-173-389\",
\"deliveryAddress\":\"м. Дніпро, відділення НП №32\",
\"url\":\"https:\/\/example.com\/offers.html\",
\"imageUrl\":\"https:\/\/example.com\/apple_iphone_xs.jpg\"
}",
            "locator": "380501234567"
        }
    ],
    "email": false
}

де в полі locator вказуємо номер телефону одержувача і додатково передаємо посилання на зображення у змінній imageUrl і посилання для кнопки — у змінній url.

Формуємо Viber-повідомлення в особистому кабінеті:

Так повідомлення виглядатиме з підстановкою даних:

6. Приклад використання з Mob push-повідомленням

Для відправлення заздалегідь підготовленого одиночного мобільного push-повідомлення тіло запиту набуває вигляду:

{
    "recipients": [
        {
            "jsonParam": null,
            "contactId": 449790707
        }
    ],
    "email": false
}

Замість contactId для ідентифікації контакту можна використовувати locator і в ньому передавати токен.

Для мобільного push-повідомлення, так само як для інших медіаканалів, доступна можливість параметризувати контент, якщо передавати дані в полі jsonParam:

Поле Custom data може містити дані в JSON-форматі і бути додатковим джерелом інформації. На боці мобільного додатку має підтримуватися така можливість використання даних.

Результатом підстановки буде приблизно такий контент, зовнішній вигляд повідомлення може відрізнятися залежно від версії операційної системи:

7. Приклад використання з web push-повідомленням

Аналогічно із запитом для Mob push-повідомлення, замість contactId для ідентифікації контакту можна використовувати locator і в ньому передавати токен.

{
    "recipients": [
        {
            "jsonParam": null,
            "contactId": 449790707
        }
    ],
    "email": false
}

Web push-повідомлення також може містити динамічний контент, для цього замість логотипу, великого зображення і посилань у редакторі повідомлень пропишемо змінні:

Тіло запиту в цьому випадку матиме такий вигляд:

{
    "recipients": [
        {
            "jsonParam": "{
\"userName\":\"Олексій\",\"productName\":\"Huawei Watch GT Black\",
\"price\":\"6999 грн\",\"https:\/\/example.com\/huawei-watch-gt\/431369.html\",
\"imageUrl\":\"https:\/\/example.com\/gallery\/huawei-watch-gt.jpeg\",
\"logo\":\"https:\/\/example.com\/Your-Logo.jpeg\",
\"moreOffer\":\"https:\/\/example.com\/more-offer.html\"
}",
            "contactId": 380470486
        }
    ],
    "email": false
}

У результаті підстановки даних із запиту користувач побачить повідомлення так: 

8. Висновки

Сферою застосування ресурсу Send prepared message є відправлення триггерного повідомлення, це може бути лист про відновлення пароля, замовлення, покинутий перегляд або покинутий кошик, а також сповіщення про зміну ціни товару, яким цікавився користувач.