Ресурси API для додавання контактів

За допомогою цього методу можна додавати контакти до будь-якої групи. Видаляти контакти з групи цим методом не можна.

Запуск сценаріїв

Метод Subscribe contact створює події, тому ви можете налаштувати й запустити автоматичний сценарій для контактів, які передаються цим методом. Події створюються двох типів:

• subscribeFromApi — назва події для нових контактів;
• subscribeUpdateFromApi — назва події, якщо контакт уже є в системі.

Кожен тип події може запускати власний сценарій. Тому ви можете налаштувати різні сценарії для нових і для раніше створених контактів. Крім того, якщо у вас є кілька форм підписки, ви можете налаштувати створення інших подій, щоб запускати інші сценарії. Для цього в тілі запиту передбачено опціональний параметр formType. Його значення дописується до назви типу події через дефіс. Наприклад, якщо ви передали "formType": "abc", то події будуть такими:

• subscribeFromApi-abc — для нових контактів;
• subscribeUpdateFromApi-abc — для існуючих.

Приклад запиту з цим параметром нижче.

Кожна подія містить два параметри:

• ContactId — числовий id контакту в нашій системі;
• EmailAddress — email-адреса. Якщо ви передаєте тільки номери телефонів, цього параметру не буде.

Ці параметри можна використовувати в сценарії в такому вигляді: ${ім'я_параметра}. Наприклад, ${EmailAddress}.

Як ключ події використовується id контакту в нашій системі.

При успішній передачі запиту ви побачите в "Історії подій" приблизно такі події:

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

{

  "contact": {

    "channels": [{

        "type": "email",

        "value": "mail@example.com"

      },{

        "type": "sms",

        "value": "380942583691"

      }],

    "firstName": "John",

    "lastName": "Smith",

    "address": {

      "town": "London",

      "region": "West",

      "address": "First str. 1",

      "postcode": "12345"

    },

    "fields": [{

        "id": "12345",

        "value": "..."

      }]

  },

  "groups": ["Subscribers"],

  "formType": "abc"

}

Не всі елементи є обов'язковими. Використовуйте ті, які вам потрібні.

Ще один приклад тут. URL для відправлення запиту: /api/v1/contact/subscribe

Add/update contacts

Тип методу: POST. Опис методу, формат тіла запиту й опис полів доступні тут.

Метод дозволяє масово або по одному додавати контакти або оновлювати існуючі. По суті замінює ручний імпорт контактів із файлу. Придатний для синхронізації бази контактів вашої CRM з базою в eSputnik. Має такі особливості:

• дозволяє одним запитом додати/оновити від 1 до 3000 контактів;
• контакти створюються одразу підтвердженими, як при імпорті;
• дозволяє додавати контакт до груп і видаляти з груп;
• контакти можуть бути додані/оновлені не одразу, а протягом кількох хвилин;
• дозволяє створювати подію для запуску сценарію для нових контактів;
• у відповіді надходить asyncSessionId, за допомогою якого методом v1/importstatus/ можна отримати статус імпорту та id контактів.

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

Не всі елементи є обов'язковими. Використовуйте ті, які вам потрібні. Формат і опис усіх полів доступні тут.

{

  "contacts": [{

      "channels": [{

          "type": "email",

          "value": "mail@example.com"

        },{

          "type": "sms",

          "value": "380942583691"

        }],

      "firstName": "John",

      "lastName": "Smith",

      "address": {

        "town": "London",

        "region": "West",

        "address": "First str. 1",

        "postcode": "12345"

      },

      "fields": [{

          "id": 12345,

          "value": "..."

        }]

    }],

  "dedupeOn": "email",

  "customFieldsIDs": [12345],

  "groupNames": ["Customers"],

  "groupNamesExclude": ["Subscribers"],

  "restoreDeleted": false,

  "eventKeyForNewContacts": "newContact"

}

Якщо масив об'єктів contacts містить externalCustomerId, то в пошуку застосовується externalCustomerId, а параметр dedupeOn ігнорується.

Масиви groupNames та groupNamesExclude використовуються відповідно для додавання в групи й видалення контактів із груп.

Параметр dedupeOn вказує, як буде перевірятися унікальність контактів. Отримавши запит, система шукатиме в базі контакти за вказаною властивістю (у цьому прикладі за email). Якщо контакт знайдено — його буде оновлено. Якщо не знайдено — буде створено новий.

URL для відправлення запиту: /api/v1/contacts

Якщо ваш API запит сформований правильно, у відповідь повертається код HTTP 200.

Запуск сценарію

При використанні цього методу події можна створити тільки для нових контактів. Щоб події створювалися, додайте в тіло запиту параметр eventKeyForNewContacts. Значенням має бути рядок з латинських символів та цифр без пробілів. Значення буде використовуватися як ключ типу події та його назви.

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

• contactId — числовий id контакту в нашій системі;
• EmailAddress — email-адреса (якщо не передана, буде порожній рядок);
• SMS — номер телефону (якщо не переданий, буде порожній рядок).

Як ключі подій використовується email-адреса, а якщо її не передано, то номер телефону.

Add contact

Тип методу: POST. Опис методу, формат тіла запиту й опис полів доступні тут.

Цей метод API просто створює новий контакт. Особливості:

• якщо контакт з таким email або телефоном уже існує, він буде оновлений;
• контакти можна створювати тільки по одному;
• контакти створюються одразу підтвердженими. Налаштувати double opt-in неможливо;
• події не створює. Сценарій запустити неможливо.

URL для відправлення запиту: /api/v1/contact

Update contact

Тип методу: PUT. Опис методу, формат тіла запиту й опис полів доступні тут.

Метод тільки для оновлення одного контакту. Особливості:

• оновлює тільки по одному контакту за запит;
• ідентифікація контакту можлива тільки за id;
• події не створює. Запустити сценарій неможливо.

URL для відправлення запиту: /api/v1/contact/{id}

Замість {id} треба підставляти числовий ідентифікатор контакту в нашій системі. Його можна отримати, наприклад, за допомогою методу для пошуку контактів за email або іншими параметрами Search contacts.

Використання ідентифікаторів може бути незручним. Тому ви можете оновлювати контакти за email або телефоном за допомогою методу Add/update contacts.

Add/update contacts from external file

Тип методу: POST. Опис методу.

Додає або оновлює контакти із зовнішнього файлу. Ви можете викласти файл із контактами на своєму сервері, а за допомогою цього методу запускати імпорт контактів з нього. У запиті передається посилання на файл. Наша система завантажує файл та імпортує контакти з нього. Можливості методу такі самі, як у методу Add/update contacts, за винятком того, що дані за контактами передаються не в самому запиті, а зберігаються в окремому файлі.

Особливості методу:

• контакти передаються не в тілі запиту, а в окремому файлі;
• контакти створюються одразу підтвердженими, як при імпорті;
• дозволяє додавати контакт у групи і видаляти з груп;
• контакти можуть бути додані/оновлені не одразу, а протягом кількох хвилин;
• дозволяє створювати подію для запуску сценарію для нових контактів.

Файл має бути у форматі CSV у кодуванні UTF-8. Вимоги до файлу і формат тіла запиту описані тут.

Файл необхідно розмістити на http-ресурсі. URL цього файлу вказується в тілі запиту в параметрі link. Логін і пароль для доступу до файлу прописуйте в URL.

Запити мають відправлятися на цей URL: /api/v1/contacts/upload.

Attach contact to static segment

Тип метода: POST. Опис методу.

Додає контакти до груп типу “Список” за contactId або externalCustomerId (у запиті може бути лише один з цих параметрів). Максимальна кількість контактів в одному запиті – 500.

URL для надсилання запиту: /api/v1/group/{id}/contacts/attach

Замість {id} треба підставляти числовий ідентифікатор групи в нашій системі.

Формат тіла запиту та опис полів доступні тут.

Delete from static segment

Тип методу: POST. Опис методу.

Видаляє контакти з групи типу “Список” за contactId або externalCustomerId (у запиті може бути лише один цих параметрів).

Якщо не вказати ідентифікатори, всі контакти буде видалено з групи.

URL для надсилання запиту: /api/v1/group/{id}/contacts/detach

Замість {id} треба підставляти числовий ідентифікатор групи в нашій системі.

Формат тіла запиту та опис полів доступні тут.

Інші методи API, за допомогою яких можна створити контакт

Існує кілька методів API, які мають інше призначення, але в деяких випадках результатом їхнього використання є створення контакту. У всіх таких випадках контакт створюється підтвердженим і не потрапляє до жодних груп.

Методи для відправлення повідомлень (email/sms).

Якщо відправити повідомлення одержувачу, якого ще немає в базі, то такий контакт створюється в момент відправлення. Новому контакту буде передано тільки канал зв'язку (email або номер телефону). Жодні інші поля не заповнюються. До жодних груп контакт не потрапляє. Події не створюються.

• Send email message
• Send SMS message
• Send prepared message

Метод передачі замовлень.

При додаванні замовлення до нашої системи вона перевіряє, чи існує в базі контакт із зазначеним у замовленні телефоном або email-адресою. Якщо ні — створює новий контакт. Новому контакту будуть передані деякі дані із замовлення (якщо вони передані): email-адреса, номер телефону, ім'я та прізвище. Зауважте, що якщо контакт у базі вже є, то його не буде оновлено. Ім'я та прізвище із замовлення до нього не запишуться.

При використанні цього методу в системі створюються події. Тому ви можете здійснити певні операції з контактом, який зробив замовлення, у сценарії. Наприклад, його можна додати до групи.

• Add orders

Створення/оновлення контакту за допомогою події та сценарію.

Можна передавати за API подію для запуску сценарію, в якому можливе налаштування створення або оновлення контакту. У сценаріях для цього передбачено відповідні блоки. У параметрах події треба передавати email контакту й рядок спеціального формату для заповнення полів контакту.

• Generate event

Перегляд джерела, за допомогою якого контакт додано до системи

Ви завжди можете побачити, яким методом контакт було додано до системи

Для цього перейдіть у Контакти → Усі контакти і навпроти потрібного контакту натисніть лупу.

Відкриється вікно, де буде інформація щодо контакту

У графі “Джерело” ви побачите необхідну інформацію.

Назви джерел для різних методів

Основні методи:

• Subscribe contact (Форма підписки)
• Add/update contacts (Імпорт контактів)
• Add contact (API)
• Add/update contacts from external file (Імпорт контактів)

Методи для відправлення повідомлень (email/sms):

• Send email message (Одиночне повідомлення)
• Send SMS message (Одиночне повідомлення)
• Send prepared message (Одиночне повідомлення)

Метод передачі замовлень:

• Add orders (Інтеграція замовлень для RFM)