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

Надсилайте токени пачками до 3000 в одному запиті — так само, як при масовому завантаженні контактів.

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

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

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

Автоматичного співставлення телефону й токена в Telegram немає — ваша власна інтеграція має передавати телефон і токен разом в одному API-запиті. Інтеграція з BigQuery підтримує лише регулярні сценарії, не подієві.

Після прив’язування токена Telegram-бота до контакту Telegram Bot може повертатися в масиві channels ресурсами API Get contact і Search for contacts.

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

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

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

Якщо масова або тригерна Telegram-розсилка завершується помилкою Unauthorized, авторизація бота більше не чинна. Можливі причини з довідника помилок Telegram: USER_DEACTIVATED (користувача бота видалено або деактивовано), SESSION_REVOKED (авторизацію відкликано через завершення всіх сесій), SESSION_EXPIRED (авторизація протермінована). Перевірте токен бота та перепідключіть канал.