Використання API-ресурсу event

Email

Омніканальність

Автоматизація

Використання API-ресурсу Generate event

Універсальний ресурс Generate event може бути використаний для передавання до листа будь-яких кастомних даних, наприклад:

  • про зміну/відновлення логіну/паролю;
  • замовлення;
  • покинуті перегляди та кошики;
  • незавершену реєстрацію;
  • передавання активності клієнта на сторінці сайту або в мобільному застосунку.

Ресурс генерує подію, яка пізніше запускає сценарій для відправлення повідомлення, створення або оновлення контакту.

Важливо

Методи API версії 2 не потребують екранування вкладеного JSON.

Використання для покинутих кошиків і переглядів

Приклад запиту:

{
    "eventTypeKey": "abandoned_cart",
    "keyValue": "site@com.net",
    "params":
    [
        {
            "name": "email",
            "value": "site@ukr.net"
        },
        {
            "name": "items",
            "value":
            {
                "array":
                [
                    {
                        "name": "Кондиціонер для сухого волосся",
                        "price": "341",
                        "url": "https://site.com/catalog/suhaya-detskaya-molochnaya-smes-hipp-combiotic-2-750-g",
                        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
                        "brand": "Le Petit Olivier",
                        "tags_weight": "200",
                        "tags_oldprice": "467"
                    },
                    {
                        "name": "Magnolia Nobile Парфумована вода",
                        "price": "2341",
                        "url": "https://site.com/catalog/suhaya-detskaya-molochnaya-smes-hipp-combiotic-2-750-g",
                        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
                        "brand": "Acqua Di Parma",
                        "tags_weight": "100",
                        "tags_oldprice": "4467"
                    }
                ]
            }
        }
    ]
}

eventTypeKey – це строковий ідентифікатор типу події. Якщо до цього його не існувало, після першого запиту він з'явиться в обліковому записі, і його можна буде побачити в розділі “Тригери” → “Типи подій”.

Редагування події

Параметри події можна переглянути у вкладці “Тригери” → “Історія подій” → клікнути потрібну подію у списку.

Перегляд історії подій

  • keyValue – ключ події;
  • params – параметри події, які можна використовувати у повідомленні та сценарії.

Обмежень за кількістю параметрів немає.

Обов'язковий формат – масив {"name": "email","value": "site@ukr.net"}.

Це означає, що у даних зберігається змінна email зі значенням site@ukr.net. Надалі до неї треба звернутися у сценарії, прописавши у блоці відправлення повідомлення ${email} для успішного відправлення на пошту site@ukr.net:

Створення сценарію

Масив array містить два елементи (у цьому випадку це два товари) з набором змінних name, price, url, imageurl, brand, tags_weight, tags_oldprice. Обмежень за кількістю елементів немає. Назви змінних можуть бути довільними.

З метою використання у повідомленні даних з масиву array у блоці відправлення повідомлення в пункті JSON треба вказати назву поля items:

Заповнення пунктів налаштувань

Дані з події можна підставити повідомлення за допомогою velocity-конструкцій.

Для звертання до даних можна використовувати цикл:

#foreach($!item in $!data.get('array'))
$!item.get('name')
$!item.get('price')
$!item.get('url')
$!item.get('imageurl')
$!item.get('brand')
$!item.get('tags_weight')
$!item.get('tags_oldprice')
#end

Можна звертатися напряму за індексом до елементів масиву (відлік починається з 0). Такий спосіб звертання до даних може призводити до помилок підстановки контенту за відсутності елемента масиву.

Перший елемент:

$!data.get('array').get(0).get('name')

$!data.get('array').get(0).get('price')

$!data.get('array').get(0).get('url')

$!data.get('array').get(0).get('imageurl')

$!data.get('array').get(0).get('brand')

$!data.get('array').get(0).get('tags_weight')

$!data.get('array').get(0).get('tags_oldprice')

Другий елемент:

$!data.get('array').get(1).get('name')

$!data.get('array').get(1).get('price')

$!data.get('array').get(1).get('url')

$!data.get('array').get(1).get('imageurl')

$!data.get('array').get(1).get('brand')

$!data.get('array').get(1).get('tags_weight')

$!data.get('array').get(1).get('tags_oldprice')

І так далі.

Важливо

Звертатися до змінних слід з урахуванням регістру, оскільки змінні є регістрозалежними. Якщо в листі вказано $!item.get('ImageUrl'), а в запиті надсилається imageurl, змінну не буде підставлено. Також типовою помилкою є кириличні символи у змінних — їх треба вводити виключно латиницею.

Переглянути та перевірити підставляння динамічних даних у режимі попереднього перегляду можна за допомогою кнопки “Налаштування динамічного контенту”:

Підстановка динамічного контенту

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

Куди вводити масив даних

Після чого натисніть кнопку "Перегляд повідомлення"

  • У разі помилки під час підставляння динамічного контенту слід перевірити коректність синтаксису velocity-виразу в повідомленні.
  • Якщо ви бачите помилку “Неправильний формат”, перевірте синтаксис запиту JSON.
  • Якщо помилок немає, але дані не підставилися під час попереднього перегляду, перевірте, чи приведені до єдиного вигляду змінні в запиті та змінні в листі, чи коректно прописані звертання до змінних.
  • Якщо помилок немає і дані підставилися, можна проводити тест, передаючи запит по API до акаунта.

Використання для створення/оновлення контакту

Приклад запиту:

{
    "eventTypeKey": "create_contact",
    "keyValue": "site@com.net",
    "params":
    [
        {
            "name": "email",
            "value": "site@ukr.net"
        },
        {
            "name": "phone",
            "value": "380501234567"
        },
        {
            "name": "externalCustomerId",
            "value": "AV13760"
        },
        {
            "name": "json",
            "value":
            {
                "profileInputs":
                [
                    {
                        "profileInputId": 10001,
                        "value": "2020-11-23"
                    }
                ]
            }
        }
    ]
}

де

  • 10001 – id додаткового поля.
  • 2020-11-23 – значення додаткового поля.

Зверніть увагу на коректність даних, що передаються:

  • довжина імені та прізвища (до 60 символів);
  • коректний номер телефону в міжнародному форматі: (+380501348460);
  • значення додаткового поля контакту, яке відповідає його формату.

У разі некоректного передавання даних весь масив для оновлення полів контакту буде проігнорований системою і додавання даних до картки контакту не буде здійснено.

Для коректної роботи сценарію в блоках "Створити контакт"/"Оновити контакт" необхідно в полі EmailAddress прописати змінну із запиту – ${email}, а в полі JSON – масив для створення/оновлення контакту – ${json}.

Підстановка змінних

Детальний опис блоку “Завдання” для створення та оновлення контакту ви знайдете в цій інструкції.

Використання для відправлення сервісних листів

Розглянемо на прикладі запуску листа про відновлення пароля. 

Приклад запиту:

{
"eventTypeKey": "password_recovery",
"keyValue": "site@com.net",
"params": [{
"name": "EmailAddress",
"value": "site@ukr.net"
},
{
"name": "password",
"value": "12345678"
}
]
}

У сценарії необхідно використовувати блок "Завдання" - "Обов'язковий email", а в листі, який буде надіслано, вказати змінну $!data.get('password')

Сценарій Welcome-розсилки

Детальний опис блоку “Завдання” ви знайдете в цій інструкції.

Використання для перевірки даних контактів у подіях

Ви можете перевірити дані контактів у подіях, використовуючи метод Generate event.

Встановіть значення contactJson у params як параметр name.

{
  "params": [
    {
      "name": "contactJson",
      "value": "..."
    }
  ]
}

Вкажіть дані, які ви хочете перевірити, у полі value.

Наприклад:

{"firstname":"...","lastname":"...","sms":"...","town":"...","timeZone":"Etc/GMT+03","languageCode":"uk","profileInputs":
[{"profileInputId":10001,"value":"..."}],"confirmed":false}

Коли ви надсилаєте цей запит, використовуючи метод Generate event, API-ресурс розуміє це як отримання нового контакту і виконує перевірку даних.

Якщо дані є недійсними, метод повертає відповідь “400 Bad Request”. Відповідь містить неприпустимі поля та відомості про помилку.

Крім того, що ресурс Generate event можна використовувати для створення/оновлення контакту і запуску сценарію з можливістю підставляння динамічного контенту до тіла повідомлення, цей ресурс можна використовувати для передавання замовлень до системи. Цьому питанню присвячена тематична стаття.

Залишилися питання?
Спеціалісти обов'язково нададуть відповідь та допоможуть вирішити вашу проблему!
Зворотний дзвінок
Залишіть заявку – і наш спеціаліст зв'яжеться з вами в робочий час.
Відправити заявку
Консультація в чаті
Готові до ваших запитань!
Написати в чат
Електронна пошта
Напишіть в службу підтримки eSputnik.
Надіслати email