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

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

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

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

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

  • /v1/contact (Тип методу: POST). Метод додавання одного контакту. Завжди створює новий контакт, навіть якщо в базі вже є контакти з таким email або номером телефону, тому можуть виникати дублікати. Оновлювати існуючі контакти цим методом неможливо. Детальніше.

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

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

Додатково:

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

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

/v1/contact/subscribe

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

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

  • нові контакти створюються з непідтвердженими email-адресами;

  • можна додавати тільки по одному контакту за запит;

  • контакти створюються максимально швидко й позачергово;

  • у системі створюються події для запуску сценаріїв;

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

Важливо!

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

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

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

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

  • 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

/v1/contacts

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

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

  • дозволяє одним запитом додати/оновити від 1 до 1000 контактів;

  • контакти створюються одразу підтвердженими, як при імпорті;

  • дозволяє додавати контакт до груп і видаляти з груп;

  • контакти можуть бути додані/оновлені не одразу, а протягом кількох хвилин;

  • дозволяє створювати подію для запуску сценарію для нових контактів;

  • у відповіді надходить 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"

}

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

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

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

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

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

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

  • contactId — числовий id контакту в нашій системі;

  • EmailAddress — email-адреса (якщо не передана, буде порожній рядок);

  • SMS — номер телефону (якщо не переданий, буде порожній рядок).

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

/v1/contact

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

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

  • якщо контакт з таким email або телефоном уже існує, його не буде оновлено, а буде створено новий контакт (дублікат);

  • контакти можна створювати тільки по одному;

  • контакти створюються одразу підтвердженими. Налаштувати double opt-in неможливо;

  • події не створює. Сценарій запустити неможливо.

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

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

/v1/contact/{id}

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

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

  • оновлює тільки по одному контакту за запит;

  • ідентифікація контакту можлива тільки за id;

  • події не створює. Запустити сценарій неможливо.

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

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

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

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

/v1/contacts/upload

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

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

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

  • контакти передаються не в тілі запиту, а в окремому файлі;

  • контакти створюються одразу підтвердженими, як при імпорті;

  • дозволяє додавати контакт у групи і видаляти з груп;

  • контакти можуть бути додані/оновлені не одразу, а протягом кількох хвилин;

  • дозволяє створювати подію для запуску сценарію для нових контактів.

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

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

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

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

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

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

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

  • /v1/message/email

  • /v1/message/sms

  • /v1/message/{id}/send

  • /v1/message/{id}/smartsend

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

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

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

  • /v1/orders

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

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

  • /v1/event

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

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

Джерело контакту

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

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

Перегляд контакту

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

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

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

  • /v1/contact/subscribe (Форма підписки)

  • /v1/contacts (Імпорт контактів)

  • /v1/contact (API)

  • /v1/contacts/upload (Імпорт контактів)

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

  • /v1/message/email (Одиночне повідомлення)

  • /v1/message/sms (Одиночне повідомлення)

  • /v1/message/{id}/send (Одиночне повідомлення)

  • /v1/message/{id}/smartsend (Одиночне повідомлення)

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

  • /v1/orders (Интеграция заказов для RFM)

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

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