Вебхуки для відстеження активності
Webhooks (укр. — вебхуки) — метод відстеження в режимі реального часу певних подій у системі eSputnik та сповіщення про них сторонніх URL.
В eSputnik є два способи для налаштування та використання вебхуків:
1. Додавання зовнішнього URL для аккаунту, щоб відслідковувати активності користувачів.
2. Налаштування кастомних запитів в сценаріях через спеціальний блок Webhook.
Вебхуки для відстежування активностей
Ця функціональність дозволяє в режимі реального часу отримувати інформацію про всі активності контактів. Дані надходитимуть регулярно на вказаний URL POST запитами, як описано нижче.
Для порівняння/альтернативи є метод API Get contacts activity. Він працює при надсиланні з вашого боку GET запитів, в яких можна вказувати інтервал часу (не більше 3 місяців) та параметри (email, статус тощо).
За допомогою вебхуків можна отримувати інформацію про події у всіх медіаканалах:
- доставлено;
- помилка доставлення;
- прочитано;
- одержувач перейшов за посиланням;
- одержувач відписався від розсилок;
- одержувач поскаржився на спам;
- підписки, унікальні перегляди та конверсія для віджетів.
Як впровадити вебхуки?
Вам необхідно сконфігурувати на своєму сервері URL, на який ви бажаєте отримувати повідомлення — POST-запити у форматі JSON та обробляти дані щодо них.
Потім цей URL необхідно додати до налаштувань eSputnik. Для цього авторизуйтеся в системі, зайдіть до налаштувань акаунта, розділ «Лабораторія». Активуйте опцію «Webhooks» і вставте ваш URL у поле «Webhook адреса».
Далі почнеться миттєва перевірка URL-адреси GET-запитом. Якщо раптом виникнуть помилки, то, можливо, на вашому боці спрацює блокування нашого запиту з різних причин. Про точну причину можна дізнатися за кодом помилки сервера на вашому боці.
Система перевірить доступність URL-адреси. Якщо все відбулося успішно, то налаштування завершене.
Після цього здійсніть будь-яку дію в акаунті. Наприклад, надішліть собі листа. Протягом кількох хвилин за вказаною адресою буде відправлений POST-запит з інформацією про останні активності. POST-запити відправлятимуться в форматі JSON при виникненні активності користувачів (відправлення email, відкривання повідомлення, перехід тощо).
Якщо webhook URL не повертає код відповіді HTTP 200, то спроба POST-запиту буде повторюватися із зростаючими інтервалами (1 хвилина, 2 хвилини, 4 хвилини, 8 хвилин і так до одного запиту на годину). Наступні запити будуть відкладені до успішного відправлення першого, а потім також відправлятимуться послідовно.
Можливі параметри
Параметр | Тип | Опис |
activityDateTime | string | Дата й час, коли відбулася активність |
activityStatus | string |
|
broadcastId | int | Ідентифікатор розсилки |
clickEventLink | string | Містить посилання, за яким перейшов контакт (при статусі CLICKED) |
contactId | int | Ідентифікатор контакту |
string | Email контакту | |
externalCustomerId | string | Унікальний ідентифікатор контакту у системі клієнта |
hardBounce | bool | Це поле повертається, тільки якщо статус UNDELIVERED. Параметр сповіщає про наявність контакту в чорному списку.
|
iid | string | Службовий параметр |
mediaType | string | Медіатип (SMS, Email, Web Push, Viber, Mobile Push, AppInbox, Widget, In-App, Telegram) |
messageId | int | Ідентифікатор повідомлення |
messageInstanceId | int | Ідентифікатор екземпляра повідомлення |
messageName | string | Назва повідомлення (відсутнє значення для тестових повідомлень) |
messageTag | string | Мітка повідомлення |
mobilepush | string | Token підписника мобільного застосунку |
sms | string | Номер телефону контакту |
sourceEventId | int | Ідентифікатор події |
sourceEventKey | string | Ключ типу події |
sourceEventTypeId | int | Ідентифікатор типу події |
sourceEventTypeKey | string | Значення ключа події |
statusData | Масив із даними | |
statusDescription | string | Це поле повертається тільки у випадку статусу UNDELIVERED. Містить причину, з якої повідомлення не було доставлене. Це може бути відповідь сервера одержувача, відповідь системи про неможливість відправити повідомлення etc |
subscripton | Масив із даними | |
subscriptons | array of string | Ключі категорій підписок |
viber | string | Номер телефону контакту |
viewMessageLink | string | Містить посилання на веб-версію повідомлення |
webpush | string | Token підписника веб-повідомлень |
workflowBlockId | string | Службовий параметр сценарія |
workflowId | int | Ідентифікатор сценарія |
workflowInstanceId | int | Ідентифікатор окремого запуску сценарію. Використовуйте його для угрупування розсилок у рамках запуску одного сценарію. |
Нижче наведено тестові приклади вебхуків у вигляді масиву JSON з усіма можливими варіантами статусів.
Для масових розсилок:
[ { "broadcastId": 3459207, "messageName": "test", "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18", "contactId": 1967597908, "externalCustomerId": "789456512", "email": "test1@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702518, "activityDateTime": "2023-09-14T08:30:03", "viewMessageLink": "https://u51739.esclick.me/J9o6EvyAKGmB", "statusData": {} }, { "broadcastId": 3459207, "messageName": "test", "iid": "4af20897-de88-4ad0-ada3-dc4bcf14e8d8", "contactId": 889891911, "externalCustomerId": "262ac297-6ae1-11ec-a2ec-0050569bdf92", "email": "test2@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702518, "activityDateTime": "2023-09-14T08:30:03", "viewMessageLink": "https://u51739.esclick.me/J9o6Dl1wrDeB", "statusData": {} }, { "broadcastId": 3459207, "messageName": "test", "iid": "b14dec37-806e-4bc4-ba71-a5911a7d7ce4", "contactId": 1026901517, "email": "test3@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702518, "activityDateTime": "2023-09-14T08:30:03", "viewMessageLink": "https://u51739.esclick.me/J9o6Dttf6fOB", "statusData": {} }, { "broadcastId": 3459207, "messageName": "test", "hardBounce": false, "iid": "99d591ab-e7a5-49ed-8e16-b3023378fc18", "contactId": 1967597908, "externalCustomerId": "789456512", "email": "test1@yourdomain.com", "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", "statusData": {} } ]
JSON
Для тригерних розсилок:
[ { "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": "test1@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702524, "activityDateTime": "2023-09-14T08:30:50", "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsdn2P", "statusData": {} }, { "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": "test1@yourdomain.com", "mediaType": "email", "activityStatus": "DELIVERED", "messageId": 2489300, "messageInstanceId": 4702524, "activityDateTime": "2023-09-14T08:30:51", "viewMessageLink": "https://u51739.esclick.me/1RocjPwr0MwONsd3gP", "statusData": {} }, { "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", "statusData": {} } ]
JSON
Практичне застосування вебхуків
Цей функціонал дозволяє отримувати в режимі реального часу інформацію про всі активності контакту без запитів інформації з вашого боку. Інформація надходитиме регулярно на вказаний URL POST-запитами, як описано вище.
Для порівняння/альтернативи існує метод API Get contacts activity.
Він працює при відправленні з вашого боку GET-запитів, у яких можна вказувати інтервал часу (не більше 3 місяців) і параметрів (email, статус тощо).
Документація: https://docs.esputnik.com/reference/contactactivity-1
Протестуйте на реальних розсилках