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

📘

Примітка

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

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

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

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

1. Відкрийте @BotFather у Telegram.
2. Відправте команди

• /start
• /newbot

3. Виконайте інструкції з налаштування бота. 
4. Після створення бота ви отримаєте токен доступу. Скопіюйте його.

5. Перейдіть до налаштувань вашого облікового запису eSputnik на вкладку Мої боти і натисніть Підключити Telegram-бот.

6. Введіть токен у відповідне поле і натисніть Зберегти.

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

1. На вкладці Мої боти натисніть Підключити Telegram-бот.
2. Натисніть Підключити наявний Telegram-бот.

3. У чаті @BotFather введіть команду /mybots, виберіть потрібний бот зі списку, скопіюйте його токен, додайте його у відповідне поле і натисніть Зберегти.

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

📘

Примітка

Загальна кількість підписників 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), який передається, коли користувач блокує бот.