Вебхуки для відстеження активності
Вебхуки — це метод відстеження в реальному часі активності контактів у системі eSputnik і надсилання сповіщень про цю активність на клієнтську URL-адресу.
Вебхуки налаштовуються шляхом додавання зовнішньої URL-адреси до вашого акаунта, після чого ви зможете автоматично отримувати дані про дії контактів у різних медіаканалах за допомогою POST запитів.
Система надсилає запити на ваш сервер щоразу, коли відбувається одна з таких подій:
- Доставлено — повідомлення надійшло контактові;
- Не доставлено — повідомлення не вдалося доставити;
- Читали — контакт відкрив повідомлення;
- Відписалися — контакт відмовився від розсилки;
- Переходили — контакт натиснув на посилання в повідомленні;
- Спам — повідомлення було позначено як спам.
Примітка
Перед налаштуванням вебхуків необхідно сконфігурувати на своєму сервері URL, на який ви бажаєте отримувати повідомлення — POST-запити у форматі JSON та обробляти дані щодо них.
Створення експорту даних
Перейдіть до налаштувань вашого акаунта на вкладку “Експорт даних”, натисніть кнопку “Новий експорт даних” і виберіть “Вебхук”.
Підключення
Додайте назву вебхука і вкажіть URL-адресу, яку ви раніше сформували на своєму сервері.
Autentification (опційно)
Якщо на вашому сервері увімкнено аутентифікацію, вкажіть логін і пароль, які ваш сервер використовує для приймання запитів. Для цього активуйте перемикач “Authentication” і заповніть відповідні поля.
Експорт статусів активності
За замовчуванням обрані усі статуси для відстеження активності. Якщо необхідно, ви можете змінити цей перелік — деактивуйте прапорці біля потрібних.
Після налаштування експорту даних через вебхук натисніть кнопку “Зберегти”.
Вебхук стане активним, а дані надходитимуть в реальному часі на вказану URL-адресу.
Перевірка налаштувань
Система перевірить доступність URL-адреси GET-запитом. Якщо виникнуть помилки, то, можливо, на вашому боці спрацює блокування нашого запиту з різних причин. Про точну причину можна дізнатися за кодом помилки сервера на вашому боці.
Якщо все відбулося успішно, то налаштування завершене.
Після цього здійсніть будь-яку дію в акаунті. Наприклад, надішліть собі листа. За вказаною адресою буде відправлений POST-запит у форматі JSON з інформацією про останні активності.
Наприклад, якщо контакт отримав лист, відкрив його і натиснув на посилання, система послідовно надішле три запити зі статусами DELIVERED, READ, CLICKED.
Якщо URL-адреса вебхука не повертає код відповіді HTTP 200, то спроба POST-запиту буде повторюватися із зростаючими інтервалами (1 хвилина, 2 хвилини, 4 хвилини, 8 хвилин і так до одного запиту на годину). Наступні запити будуть відкладені до успішного відправлення першого, а потім також відправлятимуться послідовно.
Деактивація вебхука
Щоб деактивувати вебхук, наситність значок три крапки, виберіть “Деактивувати вебхук” та підтвердьте дію.
Деактивація призупиняє надсилання запитів, сам вебхук залишається збереженим у системі і його можна буде активувати пізніше.
Редагування експорту даних
Для внесення змін до налаштувань, натисніть на назву вебхука, відредагуйте дані та збережіть налаштування.
Можливі параметри
| Параметр | Тип | Опис |
|---|---|---|
| activityDateTime | string | Дата й час, коли відбулася активність. |
| activityStatus | string | - SENT – повідомлення відправлено (тільки для каналу Mobile Push) - DELIVERED – повідомлення доставлене. - UNDELIVERED – повідомлення не доставлене (у параметрі statusDescription описано причину). - READ – повідомлення прочитане. - UNSUBSCRIBED - контакт відписався від розсилок. - CLICKED – контакт переходив за посиланнями в повідомленні. - SPAM – контакт поскаржився на спам - SUBSCRIPTION_CHANGED – контакт змінив категорію підписки. |
| broadcastId | int | Ідентифікатор розсилки. |
| clickEventLink | string | Містить посилання, за яким перейшов контакт (при статусі CLICKED). |
| contactId | int | Ідентифікатор контакту. |
| string | Email контакту. | |
| externalCustomerId | string | Унікальний ідентифікатор контакту у системі клієнта. |
| hardBounce | bool | Це поле повертається, тільки якщо статус UNDELIVERED. Параметр сповіщає про наявність контакту в чорному списку. - false – не в чорному списку на момент відправлення повідомлення. - true – у чорному списку на момент відправлення. |
| 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 | 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": "[email protected]",
"mediaType": "email",
"activityStatus": "DELIVERED",
"messageId": 2489300,
"messageInstanceId": 4702518,
"activityDateTime": "2023-09-14T08:30:03",
"viewMessageLink": "https://s8.esclick.me/1GlIGhju6umq",
"statusData": {}
},
{
"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://s8.esclick.me/1GlIGhju6umq",
"statusData": {}
},
{
"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://s8.esclick.me/1GlIGhju6umq",
"statusData": {}
},
{
"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://s8.esclick.me/1GlIGhju6umq",
"statusData": {}
}
]
Для тригерних розсилок:
[
{
"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://s8.esclick.me/1GlIGhju6umq",
"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": "[email protected]",
"mediaType": "email",
"activityStatus": "DELIVERED",
"messageId": 2489300,
"messageInstanceId": 4702524,
"activityDateTime": "2023-09-14T08:30:51",
"viewMessageLink": "https://s8.esclick.me/1GlIGhju6umq",
"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": {}
}
]
Альтернативні методи отримання статусів активності
Для порівняння/альтернативи існує метод API Get contacts activity.
Він працює при відправленні з вашого боку GET-запитів, у яких можна вказувати інтервал часу (не більше 3 місяців) і параметрів (email, статус тощо).
Updated 2 days ago