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

Вебхуки — це метод відстеження в реальному часі активності контактів у системі eSputnik і надсилання сповіщень про цю активність на URL-адресу клієнта.

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

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

Доставлено — повідомлення надійшло контактові;
Не доставлено — повідомлення не було доставлено;
Читали — контакт відкрив повідомлення;
Відписалися — контакт відмовився від розсилки;
Переходили — контакт натиснув на посилання в повідомленні;
Спам — повідомлення відзначене як спам;
Змінено підписку — контакт змінив категорію підписки на розсилку.

📘
Примітка
Перед налаштуванням вебхуків необхідно сконфігурувати на своєму сервері URL, на який ви бажаєте отримувати повідомлення — POST-запити у форматі JSON, а також забезпечити їх обробку.

Створення експорту даних

Перейдіть у налаштування акаунта на вкладку Експорт даних, натисніть кнопку Новий експорт даних і виберіть Вебхук.

Підключення

Додайте назву вебхука і вкажіть URL-адресу, яку ви раніше підготували на своєму сервері.

Аутентифікація (опційно)

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

Експорт статусів активності

За замовчуванням обрані всі статуси. За потреби ви можете змінити перелік — зніміть прапорці біля непотрібних.

Після налаштування експорту натисніть кнопку Зберегти.

Вебхук стане активним, і дані надходитимуть у реальному часі на зазначену URL-адресу.

Перевірка налаштувань

Система перевіряє доступність URL-адреси за допомогою GET-запиту. Якщо виникають помилки, можливо, ваш сервер блокує запит. Точну причину можна визначити за кодом помилки.

Якщо перевірка успішна — налаштування завершене.

Після цього виконайте будь-яку дію в акаунті (наприклад, надішліть собі листа). За вказаною адресою буде відправлений POST-запит у форматі JSON з інформацією про активність.

Наприклад, якщо контакт отримав лист, відкрив його і натиснув на посилання, система послідовно надішле три запити зі статусами: DELIVERED, READ, CLICKED.

Деактивація / Видалення вебхука

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

📘
Примітка
Деактивація призупиняє надсилання запитів, але сам вебхук зберігається в системі, і його можна повторно активувати пізніше.

Редагування експорту даних

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

Можливі параметри

Параметр	Тип	Опис
activityDateTime	string	Дата й час, коли відбулася активність.
activityStatus	string	SENT – повідомлення відправлено (тільки для каналу Mobile Push). DELIVERED – повідомлення доставлене. UNDELIVERED – повідомлення не доставлене (причина описана в параметрі statusDescription). READ – повідомлення прочитане. UNSUBSCRIBED - контакт відписався. CLICKED – контакт натиснув на посилання. Генерується для кожного кліку по кожному посиланню в повідомленні. SPAM – повідомлення позначене як спам. SUBSCRIPTION_CHANGED – контакт змінив категорію підписки.
broadcastId	int	Ідентифікатор розсилки.
clickEventLink	string	Посилання, за яким перейшов контакт (для `CLICKED`).
contactId	int	Ідентифікатор контакту.
email	string	Email контакту.
externalCustomerId	string	Унікальний ідентифікатор контакту у системі клієнта.
from	string	Ім'я відправника (Email та SMS повідомленнях).
hardBounce	bool	Повертається тільки для статусу `UNDELIVERED` і лише для каналу Email. Вказує тип помилки: `true` – помилка типу hard bounce (постійна, наприклад, скриньки не існує). `false` – помилка типу soft bounce (тимчасова, наприклад, переповнена скринька).
iid	string	Унікальний ідентифікатор відправки повідомлення.
mediaType	string	Медіатип повідомлення (SMS, Email, Web Push, Viber, Mobile Push, AppInbox, Widget, In-App, Telegram).
messageId	int	Ідентифікатор повідомлення.
messageInstanceId	int	Ідентифікатор екземпляра повідомлення.
messageLanguageCode	string	Код мови повідомлення.
messageName	string	Назва повідомлення (відсутнє значення для тестових повідомлень).
messageTag	string	Мітка повідомлення.
mobilepush	string	Токен підписника мобільного застосунку.
osName	string	Операційна система пристрою.
osType	string	Тип пристрою (Desktop/Mobile).
sms	string	Номер телефону контакту.
sourceEventId	int	Ідентифікатор події.
sourceEventKey	string	Ключ типу події.
sourceEventTypeId	int	Ідентифікатор типу події.
sourceEventTypeKey	string	Значення ключа події.
statusDescription	string	Повертається тільки для статусу `UNDELIVERED`. Містить причину, з якої повідомлення не було доставлене. Наприклад, відповідь сервера одержувача, відмова у відправленні повідомлення тощо.
subscriptions	array of string	Ключі категорій підписок.
viewMessageLink	string	Посилання на веб-версію повідомлення (лише для Email).
webpush	string	Токен підписника веб-повідомлень.
workflowBlockId	string	Ідентифікатор блоку сценарію, що відправив повідомлення.
workflowId	int	Ідентифікатор сценарію.
workflowInstanceId	int	Ідентифікатор запуску сценарію (для групування розсилок у межах одного запуску).

Нижче наведено тестові приклади вебхуків у вигляді масиву JSON з усіма можливими варіантами статусів.

Для масових розсилок:

[
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4",
    "contactId": 1026901517,
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:03",
    "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB"
  },
  {
    "broadcastId": 3459207,
    "messageName": "test",
    "hardBounce": false,
    "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18",
    "contactId": 1967597908,
    "externalCustomerId": "789456512",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "UNDELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702518,
    "activityDateTime": "2023-09-14T08:30:07",
    "statusDescription": "5.1.2 (bad destination system: no such domain)",
    "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB"
  }
]

Для тригерних розсилок:

[
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_05cae26d9ae85e1eb40ed34765f9c7be",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "019b7450-52d9-11ee-85c4-959256ea468c",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:50",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P"
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_527e1f819b41bd379d75ebbe3392b879",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "iid": "01777190-52d9-11ee-917a-ef6e91bfc7c3",
    "contactId": 889891911,
    "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92",
    "email": "[email protected]",
    "mediaType": "email",
    "activityStatus": "DELIVERED",
    "messageId": 2489300,
    "messageInstanceId": 4702524,
    "activityDateTime": "2023-09-14T08:30:51",
    "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP"
  },
  {
    "messageName": "test",
    "workflowId": 340484,
    "workflowBlockId": "_be178ec8aacbf249d8bb736e9df9fd0d",
    "sourceEventKey": "9d0c163d-cc3b-4f9e-bb03-2f5d1111ef91",
    "sourceEventTypeKey": "productViewed",
    "workflowInstanceId": "da33697d-52d8-11ee-9d24-7ec2059b5114",
    "hardBounce": false,
    "iid": "01a86ca0-52d9-11ee-85c4-959256ea468c",
    "contactId": 706515632,
    "sms": "380956490955",
    "mediaType": "viber",
    "activityStatus": "UNDELIVERED",
    "messageId": 3213684,
    "messageInstanceId": 4696769,
    "messageTag": "tag2,tag,test",
    "activityDateTime": "2023-09-14T08:30:51",
    "statusDescription": "401: null"
  }
]

Альтернативні методи отримання статусів активності

Для порівняння/альтернативи існує метод API Get contacts activity.

Він працює при відправленні з вашого боку GET-запитів, у яких можна вказувати інтервал часу (не більше 3 місяців) і параметрів (email, статус тощо).

Updated 1 day ago