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

Ресурс Send prepared message дозволяє відправляти заздалегідь підготовлене повідомлення, вказуючи його ID в URL запиту. Це може бути лист про відновлення пароля, замовлення, покинутий перегляд або кошик, а також сповіщення про зміну ціни товару, яким цікавився користувач.
Особливості використання:

• В одному запиті передається до тисячі одержувачів;
• Повідомлення можна персоналізувати для кожного одержувача даними з запиту;
• Ресурс використовується в каналах Email, SMS, Mobile Push, Web Push, Viber, Telegram та App Inbox.

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

Запит здійснюється POST-методом за адресою https://esputnik.com/api/v1/message/{id}/smartsend, де {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, номер телефону, Device ID або токен контакту, на який відправлялося повідомлення;
• status — результат:
  • OK — якщо повідомлення успішно додано до черги на відправлення; про статус повідомлення можна дізнатися, використовуючи requestId і запит до ресурсу Get single message status;
  • ERROR — якщо повідомлення не вдалося додати до черги на відправлення, запит повертається зі статусом ERROR, де message — опис помилки, (наприклад: "message": "'example@mail.com' is not valid 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"
        }
    ]
}

3. Приклад використання з Email

Ресурс може використовуватися для відправлення одиночних email-повідомлень з персоналізацією та без неї. Для персоналізації використовується поле jsonParam, яке може містити JSON-об'єкти, вкладені об'єкти та масиви, які перед відправленням запиту потрібно серіалізувати, тобто послідовно перетворити об'єкти на JSON-рядок.

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

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

{
  "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 свідчить, що в листі не передбачено використання динамічної персоналізації.

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"
    }
  ]
}

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

Щоб отримати доступ до даних із масиву, в повідомленні треба використовувати конструкцію вбудованого у 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-повідомлення, на відміну від 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. Приклад використання з Mobile Push 

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

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

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

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

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

7. Приклад використання з Web Push

Аналогічно із запитом для Mobile Push повідомлення, у Web Push замість contactId для ідентифікації контакту можна використовувати locator і в ньому передавати токен, якщо contactId відсутній.

{
    "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. Приклад використання з Telegram

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

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

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

9. Приклад використання з App Inbox

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

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

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

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

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