Налаштування інтеграції з Telegram-ботом

📘

Примітка

Telegram бот є обовʼязковим для роботи каналу

Щоб робити розсилки у вашому Telegram-боті за допомогою eSputnik, виконайте наступні дії:

  1. Створіть бот у сервісі @BotFather, скопіюйте ключ доступу та завантажте його до eSputnik.
  2. Налаштуйте сервіс на власному боці, що прийматиме токени контактів (chat_id) з вашого бота і передаватиме їх до eSputnik. Ви можете зробити це у будь-який зручний для вас спосіб, приклад реалізації можна знайти за посиланням.

Створення бота в Telegram

  1. Відкрийте @BotFather у Telegram.
  2. Відправте команди
  • /start
  • /newbot
  1. Виконайте інструкції з налаштування бота. 
  2. Після створення бота ви отримаєте токен доступу. Скопіюйте його.
Токен бота
  1. Перейдіть до налаштувань вашого облікового запису eSputnik на вкладку Мої боти і натисніть Підключити Telegram-бот.
Підключити Telegram-бот
  1. Введіть токен у відповідне поле і натисніть Зберегти.
Підключення нового бота

Якщо потрібно інтегрувати вже створений бот:

  1. На вкладці Мої боти натисніть Підключити Telegram-бот.
  2. Натисніть Підключити наявний Telegram-бот.
Підключення нового бота
  1. У чаті @BotFather введіть команду /mybots, виберіть потрібний бот зі списку, скопіюйте його токен, додайте його у відповідне поле і натисніть Зберегти.
Підключення наявного бота

Після підключення бота ви отримаєте ID застосунку (app_uuid) — його потрібно використовувати в URL для відправлення запиту з додавання та оновлення токенів ваших контактів в eSputnik: https://esputnik.com/api/v1/apps/{app_uuid}/tokens.

ID застосунку

📘

Примітка

Загальна кількість підписників Telegram-бота вказана праворуч від його назви.

Створення та оновлення контактів

Щоб додати або оновити токени контактів, використовуйте API-метод Add application tokens (тип POST).

Формат JSON-запиту: 

{
  "tokens": [
    "Token"
  ]
}

Формат контактних даних у запиті:

{
    "token": string,     // required
    
    // Ідентифікатори для пошуку контакту (принаймні один є обов’язковим)
    "contactId": Long,
    "externalCustomerId": string, 
    "phone": string,
    "email": string
}

URL для відправлення запиту: /v1/apps/{app_uuid}/tokens

Запит працює наступним чином:

  • Контакт створюється з усіма ідентифікаторами, якщо в системі не існує контакту з такими ідентифікаторами.
  • Якщо ідентифікатори вже існують, вони не створюються і не оновлюються.
  • Пріоритет ідентифікаторів для пошуку контактів у системі: contactId → externalCustomerId → phone → email.
  • Якщо контакт не знайдено за жодним із ідентифікаторів contactId → externalCustomerId → phone → email, створюється новий контакт з усіма зазначеними ідентифікаторами та токеном.
  • Якщо контакт знайдено за будь-яким із ідентифікаторів contactId → externalCustomerId → phone → email, до наявного контакту буде додано токен. 

🚧

Зверніть увагу

Запити методом Add application tokens не оновлюють наявні токени, а тільки створюють нові. Наприклад, якщо у двох запитах з однаковою email-адресою будуть міститися два різні токені, в картку контакту запишуться обидва.

Для оновлення  інших контактних даних використовуйте методи Add/update a contact або Add/update contacts.

Статуси повідомлень

Відстежуються статуси SENT, FAILED та CLICKED.

Токен буде видалено з картки контакту при отриманні статусу FAILED (Forbidden), який передається, коли користувач блокує бот.