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

Використовуючи API ресурс Generate event, ви можете надсилати події зі свого вебсайту та зберігати їх у нашій системі. Ці події можна використовувати для запуску сценарію або для сегментації.

Метод API версії 3 не потребує екранування вкладеного JSON. Версію 2 відключати не планують, тому перехід на версію 3 необов'язковий — наявні інтеграції на v2 продовжують працювати. У версії 2 поле params не обов'язкове: подію можна надіслати лише з eventTypeKey і keyValue.

Дані параметрів події зберігаються протягом 2 років, і комунікації, запущені подією, можуть звертатися до її параметрів увесь цей час. Якщо надіслати ту саму подію повторно — з тими самими eventTypeKey і keyValue, але оновленими параметрами — нові дані перезапишуть збережені раніше, а попередні значення не зберігаються поряд.

Метод включає параметри, які описані в наступній таблиці.

Ви можете використовувати цей API ресурс для надсилання наступних запитів, як описано нижче.

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

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

{
  "eventTypeKey": "AbandonedCart",
  "keyValue": "2424925572",
  "params": {
    "emailAddress": "[email protected]",
    "cartItems": [
      {
        "name": "Conditioner for dry hair",
        "price": "341",
        "url": "https://site.com/conditioner-dry-hair",
        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
        "brand": "Le Petit Olivier",
        "tags_weight": "200",
        "tags_oldprice": "467"
      },
      {
        "name": "Magnolia Nobile Perfumed water",
        "price": "2341",
        "url": "https://site.com/catalog/perfumed-water-2-750-g",
        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
        "brand": "Acqua Di Parma",
        "tags_weight": "100",
        "tags_oldprice": "4467"
      }
    ],
    "recommendedItems": [
      {
        "name": "Shampoo for dry hair",
        "price": "441",
        "url": "https://site.com/shampoo-dry-hair",
        "imageurl": "https://site.com/uploads/product/big/20161122/20161122_7zvb.jpg",
        "brand": "Le Petit Olivier",
        "tags_weight": "200",
        "tags_oldprice": "467"
      },
      {
        "name": "Magnolia Nobile Face cream",
        "price": "1341",
        "url": "https://site.com/catalog/face-cream-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 – параметри події, які можна використовувати у повідомленні та сценарії.

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

Подія має містити ідентифікатор контакту, такий як email, телефон або External ID.

У нашому прикладі це емейл [email protected]. Надалі до нього треба звернутися у сценарії, прописавши у блоці відправлення повідомлення ${emailAddress} для успішного відправлення на пошту [email protected]:

Запит може містити декілька масивів. У нашому прикладі це два масиви — cartItems та recommendedItems — що містять по два товари з набором змінних name, price, url, imageurl, brand, tags_weight, tags_oldprice. Назви масивів та змінних можуть бути довільними.

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

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

#foreach($!item in $!cartItems)
$!item.name
$!item.price
$!item.url
$!item.imageurl
$!item.brand
$!item.tags_weight
$!item.tags_oldprice
#end

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

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

$!cartItems[0].name
$!cartItems[0].price
$!cartItems[0].url
$!cartItems[0].imageurl
$!cartItems[0].brand
$!cartItems[0].tags_weight
$!cartItems[0].tags_oldprice

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

$!cartItems[1].name
$!cartItems[1].price
$!cartItems[1].url
$!cartItems[1].imageurl
$!cartItems[1].brand
$!cartItems[1].tags_weight
$!cartItems[1].tags_oldprice

І так далі.

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

У модальному вікні натисніть кнопку Налаштування динамічного контенту і в полі для введення даних вставте параметри події плоским JSON-об'єктом (формат описано в статті Попередній перегляд динамічного контенту коротких повідомлень):

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

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

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

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

{
  "eventTypeKey": "create_contact",
  "keyValue": "[email protected]",
  "params": {
    "emailAddress": "[email protected]",
    "phone": "380501234567",
    "externalCustomerId": "AV13760",
    "json": {
      "profileInputs": [
        {
          "profileInputId": 10001,
          "value": "2020-11-23"
        }
      ]
    }
  }
}

де

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

Отримати ID, ключі, типи та допустимі значення додаткових полів можна за допомогою методу Get additional fields.

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

• Довжина імені та прізвища – максимум 60 символів.
• Коректний номер телефону в міжнародному форматі. Наприклад, +380001348460.
• Значення додаткового поля контакту, яке відповідає його формату.

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

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

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

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

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

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

{
  "eventTypeKey": "password_recovery",
  "keyValue": "[email protected]",
  "params": {
    "EmailAddress": "[email protected]",
    "password": "12345678"
  }
}

У сценарії необхідно використовувати блок Обов'язковий (транзакційний) Email, а в листі, який буде надіслано, вказати змінну $!password

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

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

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

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

{
  "params": {
    "contactJson": "..."
  }
}

Вкажіть дані, які ви хочете перевірити, у полі 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 можна використовувати для створення/оновлення контакту і запуску сценарію з можливістю підставляння динамічного контенту до тіла повідомлення. Цей ресурс можна використовувати для передачі замовлень до системи. Цьому питанню присвячена тематична стаття.

Збагачення профілю контакту даними про місцеперебування за IP в події

Використовуючи метод Generate event v3, можна розширити параметри події, передавши IP-адресу контакту в params. IP-адреса має бути у форматі IPv4 або IPv6.

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

{
  "keyValue": "[email protected]",
  "eventTypeKey": "welcome",
  "params": {
    "email": "[email protected]",
    "ip": "192.0.2.1"
  }
}

Подію буде доповнено параметрами, описаними в таблиці.