Налаштування інтеграції з 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.

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

Щоб додати або оновити токени контактів, використовуйте 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.
• Якщо ідентифікатор із найвищим пріоритетом не відповідає вже наявному контакту, створюється контакт з новим ідентифікатором та токеном.
• Якщо ідентифікатор із найвищим пріоритетом вже існує в eSputnik, в картку контакту буде записано токен, інші ідентифікатори будуть проігноровані. Зверніть увагу: запити методом Add application tokens не оновлюють наявні токени, а тільки створюють нові. Наприклад, якщо у двох запитах з однаковою email-адресою будуть міститися два різні токені, в картку контакту запишуться обидва.

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

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

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

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