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

Дані користувача

Email

Омніканальність

Автоматизація

Відстеження подій та поведінки

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

Основні ресурси для додавання / оновлення контактів:

  • Subscribe contact (Тип методу: POST).
    Метод застосовується для підключення форм підписки та в інших випадках. Створює нові контакти, оновлює існуючі. Створює в системі події для запуску сценаріїв. Нові контакти створюються в статусі "непідтверджений", що дозволяє реалізувати double opt-in. Детальніше.

  • Add/update contacts (Тип методу: POST).
    Метод для імпорту й оновлення контактів. Надає всі можливості для управління контактами за допомогою API. Контакти можна додавати/оновлювати масово або по одному, переміщувати по групах. Контакти створюються одразу підтвердженими, тому метод не підходить для форм підписки. Також він дозволяє створювати подію для запуску сценарію новим контактам (за винятком контактів, які раніше були додані, а потім видалені). Детальніше.

Ресурси, які можуть бути корисними для вирішення вузького кола специфічних завдань:

  • Add contact (Тип методу: POST).
    Метод для додавання або оновлення одного контакту. Детальніше.

  • Update contact (Тип методу: PUT).
    Метод для оновлення одного контакту. Нові контакти не створює. Щоб оновити контакт цим методом, треба знати id контакту в нашій системі. Детальніше.

  • Add/update contacts from external file (Тип методу: POST).
    Додавання/оновлення контактів із зовнішнього файлу. Ви можете викласти файл з контактами на своєму сервері, а за допомогою цього методу запускати імпорт контактів з нього. У запиті передається посилання на файл. Наша система завантажує файл та імпортує контакти з нього. Детальніше.

  • Attach contact to static segment (Тип методу: POST).
    Метод для додавання контактів до груп типу “Список”. Детальніше.

  • Delete from static segment (Тип методу: POST).
    Метод для видалення контактів із груп типу “Список”. Детальніше.

Додатково:

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

  • Як дізнатися, в який спосіб було створено контакт? Детальніше.

Subscribe contact

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

Метод для додавання та оновлення контактів. У першу чергу призначений для підключення форм підписки, тому має такі особливості:

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

Важливо!

Обов'язково налаштуйте процедуру підтвердження email-контакту. Як це зробити, описано тут.

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

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

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

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

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

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

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

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

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

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

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

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

Параметри події за API

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

{

  "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 контактів.

Важливо!

Нові контакти, передані цим методом, створюються з підтвердженими email. Передбачається, що ці контакти вже пройшли double opt-in в іншій системі. Відправлення розсилок контактам, які не пройшли double opt-in, є спамом.

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

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

{

  "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.

Важливо

Оскільки метод може обробляти до 3000 контактів, деякі з них можуть не зберегтись. Перелік контактів, які не було додано чи оновлено, повертається у відповіді 200 у полі failedContacts (див. приклад відповіді в документації API). Перевіряйте дані у відповіді, щоб з’ясувати причину.

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

При використанні цього методу події можна створити тільки для нових контактів. Щоб події створювалися, додайте в тіло запиту параметр 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)

Залишилися питання?
Спеціалісти обов'язково нададуть відповідь та допоможуть вирішити вашу проблему!
Зворотний дзвінок
Залишіть заявку – і наш спеціаліст зв'яжеться з вами в робочий час.
Відправити заявку
Консультація в чаті
Готові до ваших запитань!
Написати в чат
Електронна пошта
Напишіть в службу підтримки eSputnik.
Надіслати email