Использование API-ресурса event

Ресурс v1/event универсальный и может быть использован для передачи любых кастомных данных в письмо, таких как данные о

• смене/восстановлении логина/пароля,

• заказе,

• брошенных просмотрах и корзинах,

• незаконченной регистрации,

• передачи активности клиента на странице сайта или в мобильном приложении.

Ресурс генерирует событие, которое впоследствии запускает сценарий для отправки сообщения, создания или обновления контакта.

Использование для брошенных корзин и просмотров

Пример запроса:

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

}
  ]
}

После запроса на v1/event в аккаунте сгенерируется событие, которое можно найти в разделе “Триггеры” → “Типы событий”.

Содержимое события можно посмотреть во вкладке “Триггеры” → “История событий” → клик на нужное событие в списке.

• eventTypeKey – переменная, значение которой будет названием будущего события;

• keyValue – ключ события;

• params – параметры события, которые могут быть использованы в сценарии.

Ограничений на количество параметров нет.

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

Это значит, что в данных хранится переменная email со значением site@ukr.net. К ней в дальнейшем нужно обратиться в сценарии, прописав в блоке отправки сообщения ${email} для успешной отправки на почту site@ukr.net:

Обратите внимание, что содержимое поля items для корректной передачи необходимо сериализовать. Этого требует формат передачи данных, иначе JSON будет невалидным. В десериализованном виде массив выглядит так:

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

Массив array содержит два объекта (в данном случае это два товара) с набором переменных name, price, url, imageurl, brand, tags_weight, tags_oldprice. Ограничений по количеству массивов нет. Названия переменных могут быть произвольными.
Для десериализации данных массива array необходимо в блоке отправки сообщения в пункте JSON указать название поля items:

Данные из запроса можно вытянуть в сообщение с помощью Velocity.

Для обращения к данным можно использовать цикл:

$!item.get('name')
$!item.get('price')
$!item.get('url')
$!item.get('imageurl')
$!item.get('brand')
$!item.get('tags_weight')
$!item.get('tags_oldprice')

Можно обращаться напрямую по индексу к элементам массива (счет начинается с 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')

И так далее.

Просмотреть и проверить подстановку динамических данных на предпросмотре можно с помощью кнопки “Настройки динамического контента”:

В открывшемся окне в поле для ввода данных нужно вставить разэкранированный массив с динамическими данными:

Далее нажмите кнопку "Просмотр сообщения"

• В случае ошибки при подстановке динамического контента, необходимо удостовериться в корректности синтаксиса Velocity выражения в сообщении.

• Если видите ошибку “Неверный формат”, проверьте синтаксис запроса JSON.

• Если ошибок нет, но данные не подставились на предпросмотре, проверьте, приведены ли к одному виду переменные в запросе и переменные в письме, правильно ли прописаны обращения к переменным.

• Если ошибок нет и данные подставились, можно делать тест, передавая запрос по API в аккаунт.

Использование для создания/обновления контакта

Пример запроса:

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

где

• 10001 – id допполя.

• 2020-11-23 – значение дополнительного поля.

Содержимое вложенного JSON массива или объекта также подлежит сериализации.
Обратите внимание на корректность передаваемых данных:

• длина имени и фамилии: (до 60 символов),

• корректный номер телефона в международном формате: (+380501348460),

• значение дополнительного поля контакта, соответствующее его формату.

В случае некорректно передаваемых данных весь массив для обновления полей контакта будет проигнорирован системой и добавление данных в карточку контакта не произойдет.

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

Подробное описание блока  “Задача” для создания и обновления контакта описано в этом руководстве.

Использование для отправки сервисных писем

Рассмотрим на примере запуска письма о восстановлении пароля. Пример запроса:

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

В сценарии необходимо использовать блок "Задача" - "Обязательный емейл", а в письме, которое будет отправляться, указать переменную $!data.get('password')

Подробное описание блока  “Задача” описано в этом руководстве.

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