Перші кроки
Дані користувача
- Огляд адаптивного email-редактора
- Cтворення оформлення для листа
- Створення синхронізованих модулів
- Налаштування адаптивності
- Налаштування smart-контейнерів
- Оформлення промовкладки для Gmail
- Додавання Ролловера
- Додавання анкорних посилань
- Бібліотека модулів
- Додавання таблиці до листа
- Додавання кастомних шрифтів
- Створення кнопки СТA
- Робота з блоком "Зображення"
- Робота з блоком “Таймер"
- Використання ШІ в email-редакторі
Омніканальність
- SDK для мобільних застосунків
- Керування ключами доступу до мобільного SDK
- Підключення мобільного застосунку
- Створення та завантаження ключа Firebase
- Створення мобільних push-повідомлень
- Налаштування аналітики доставлень та кліків
- Планування мобільних push-повідомлень
- Типи діплінків
- Надсилання тестових повідомлень із налагодження запитів
- Налаштування віджетів для сайту
- Виклик віджета
- Налаштування геоданих для правил виклику віджетів
- Збереження даних із віджетів у поля контактів
- Захист від роздратування
- Дії після заповнення форми
- Заміна системного сценарію Double Opt-In
- Розширення для тестування форм в Google Chrome
- Створення pop-up-форм за допомогою Google Tag Manager або WordPress
- Надсилання подій з віджетів eSputnik до Google Analytics
- A/B-тестування віджетів
- Збір контактних даних за допомогою форм запитів
Автоматизація
- Налаштування та редагування сценаріїв
- Налаштування умов запуску та зупинки сценарію
- Блок “Старт”
- Група блоків “Популярні”
- Група блоків “Повідомлення”
- Використання блока повідомлень “Одне з багатьох”
- Група блоків “Контакт”
- Група блоків "Умови"
- Група блоків “Інше”
- Група блоків “Повідомлення на групу”
- Група блоків “Час”
- Розширені параметри блоків сценаріїв
- Дозволений час відправлення
- Вебхуки в сценаріях
- Відстеження історії запусків сценарію
- Якщо сценарій не працює
- Подвійне підтвердження підписки
- Вітальна серія
- Вітальна серія із сегментацією за категоріями
- Запуск сценарію після імпорту контактів
- Регулярний сценарій для групи
- Вітання з днем народження
- Привʼязка сценарію до кнопки
- Використання змінних із замовлення у сценарії
- Збір відгуків про замовлення
- Реактивація клієнтів та підписників
- Відправка розсилки непрочитавшим
- Налаштування додаткових розсилок
- Відправлення нагадувань в заданий користувачем час
- А/B-тестування в сценаріях
Персоналізація
- Підстановка промокоду з файлу
- Підстановка промокоду з використанням API
- Принципи генерації промокодів за допомогою PHP/JAVA
- Підстановка промокоду за допомогою персоналізації
- Завантаження промокодів для використання в сценарії
- Генерація промокодів у сценарії
- Відправлення промокоду за допомогою передпроцесора
- HTTP-запит для передачі промокоду з повідомлення до картки контакту
Аналітика
- Звіт щодо email-розсилки
- Звіт щодо SMS-розсилки
- Звіт щодо розсилки Web Push
- Звіт щодо Viber-розсилки
- Звіт щодо розсилки Mob Push
- Звіт щодо розсилки App Inbox
- Звіт щодо Telegram-розсилки
- Звіт зі взаємодії з In-App
- Звіт зі взаємодії з віджетами
- Звіт щодо тригерної розсилки
- Звіт щодо AMP-розсилки
- Звіт щодо мультимовної розсилки
- Налаштування передачі UTM-міток
- Візуалізація доходу
- Відстеження ефективності кампаній у Google Analytics 4
- Статистика повідомлень
Мультимовність
Відстеження подій та поведінки
- Події для запуску тригерних розсилок
- Найменування користувацьких подій
- Валідація параметрів подій
- Відстеження активності на сайті за допомогою Generate event
- Підстановка даних з подій в повідомлення
- Розгалуження сценарію в залежності від параметрів події
- Відстеження активності клієнтів у мобільних застосунках
- Вебхуки для відстеження активності
- Аналітика подій
Товарні рекомендації
API
- Поширені питання: Інтеграція з API
- API-ключі
- Ресурси API для додавання контактів
- Використання API-ресурсу Generate event
- Передача замовлень API-ресурсом Generate event
- Отримання рекомендацій щодо API ресурсом Contact recommendations based on web tracking
- Використання API-ресурсу Send prepared message
Зміна системи
Документи
Інтеграція
Використання 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 є відправлення триггерного повідомлення, це може бути лист про відновлення пароля, замовлення, покинутий перегляд або покинутий кошик, а також сповіщення про зміну ціни товару, яким цікавився користувач.