Перейти к основному содержимому

Как подключить самописного бота через API

Если вы разрабатываете собственного Telegram-бота, у вас есть максимальная гибкость в настройке его логики. Интеграция с «Откуда Подписки» через наше API позволит вам не просто отслеживать, откуда приходят подписчики, но и фиксировать всю воронку взаимодействия пользователя с ботом, передавая эти данные в рекламные системы для обучения на эти цели.

Эта инструкция предназначена для технических специалистов и разработчиков. Мы разберем, как отправлять запросы к нашему API, чтобы:

  • Фиксировать старт бота пользователем и передавать эту конверсию в Яндекс.Директ, VK, ФБ/Инста, Google Ads.
  • Передавать глубокие цели — ключевые шаги внутри воронки, такие как просмотр видео, прохождение теста, регистрация на мероприятие или оплата.
  • Отслеживать блокировку бота (отписки), чтобы понимать качество трафика из разных источников.
  • Получать доступ ко всей мощи аналитики «Откуда Подписки»: отчетам, досье подписчиков.

В этой инструкции мы подробно разберем, как с помощью нашего API настроить передачу всех необходимых событий из вашего бота.

Подготовка к интеграции​

Шаг 1 — Получите API ключ​

Любой запрос к нашему API требует аутентификации с помощью уникального ключа.

примечание

Если у вас еще нет API ключа, получите его по этой инструкции: 📘 Как получить API ключ. Это займёт 2 минуты.

Шаг 2 — Выберите тип интеграции​

Наше API поддерживает два способа интеграции. Ваш выбор будет зависеть от того, какие данные вы можете пересылать со своего сервера.

  • Вариант 1 (Рекомендуемый): Если вы можете получить JSON-объект вебхука, который присылает Telegram на ваш сервер, то всё очень просто — отправьте этот же JSON на наш API методом POST. Это самый простой и надежный способ, который открывает доступ ко всем функциям сервиса, включая трекинг отписок и расширенную аналитику по аудитории.

  • Вариант 2: Если по каким-то причинам вы не можете переслать весь JSON-объект от Telegram, есть запасной вариант. В этом случае отправьте нам данные пользователя и start-параметр через отдельный метод API.

    Чтобы трекать отписки, надо отдельно вызывать метод my_bot_was_stopped, следуйте по инструкции.

Настройка передачи старта бота​

Это самый важный шаг. Как только пользователь запускает вашего бота, вы должны сразу отправить запрос на наш сервер, чтобы зафиксировать подписку.

Вариант 1: Интеграция с использованием метода on_telegram_webhook​

Шаг 1 — Настройте пересылку вебхука от Telegram на наш API​

Когда пользователь взаимодействует с вашим ботом (например, отправляет команду /start), Telegram отправляет на ваш сервер HTTP POST-запрос с JSON-данными. Этот запрос называется вебхуком.

Что нужно сделать:

  1. Получите JSON-данные от Telegram — в вашем обработчике вебхука (endpoint, который принимает запросы от Telegram) возьмите весь JSON-объект, который пришел в теле запроса.

  2. Отправьте этот же JSON на наш API — сделайте POST-запрос на наш URL, передав в теле запроса точно такой же JSON-объект, который вы получили от Telegram, без изменений.

Настройки запроса:

  • URL для запроса:

    https://bot-api.tgtrack.ru/v1/API_КЛЮЧ/on_telegram_webhook


подсказка

Замените API_КЛЮЧ в ссылке на ваш собственный API ключ, полученный от бота «Откуда Подписки» на 📘 шаге 1.

  • Метод HTTP-запроса: POST

  • Тело запроса: Полный JSON-объект, который ваш сервер получил от Telegram в исходном виде. Не изменяйте структуру, не добавляйте и не удаляйте поля.

Пример того, что нужно отправить (содержимое входящего webhook от Telegram):

{
  "update_id": 86324345,
  "message": {
    "message_id": 123,
    "from": {
      "id": 123456789,
      "is_bot": false,
      "first_name": "Иван",
      "last_name": "Петров",
      "username": "ivanpetrov",
      "language_code": "ru"
    },
    "chat": {
      "id": 123456789,
      "first_name": "Иван",
      "last_name": "Петров",
      "username": "ivanpetrov",
      "type": "private"
    },
    "date": 1668420665,
    "text": "/start PJaf5568712cd"
  }
}

Вариант 2: Интеграция с использованием методов user_did_start_bot и my_bot_was_stopped​

Используйте эти два метода, если не можете получить исходный вебхук от Telegram, но можете получить данные пользователя, запустившего и заблокировавшего бота.

Шаг 1 — При старте бота отправьте запрос на этот метод user_did_start_bot​

  • URL для запроса:

    https://bot-api.tgtrack.ru/v1/API_КЛЮЧ/user_did_start_bot

  • Параметры запроса:

НазваниеТипОписание
user_idstringID пользователя в Telegram, с которым связано событие.
first_namestringИмя пользователя.
last_namestring(optional). Фамилия, если задана.
usernamestring(optional). Username в телеграм, если известен.
full_namestring(optional) полное имя пользователя Телеграм.
start_valuestring(optional) параметр start, с которым запустили бота.
  • Пример тела запроса:
{
  "user_id": "987654321",
  "first_name": "John",
  "last_name": "Doe",
  "username": "johnDoe5672",
  "start_value": "TGTrack-PJ123456"
}

подсказка

Чтобы трекать отписки при использовании Варианта 2, необходимо отдельно вызывать метод my_bot_was_stopped, когда пользователь блокирует вашего бота.

Шаг 1 — При блокировке бота отправьте запрос на этот метод my_bot_was_stopped​

  • URL для запроса:

    https://bot-api.tgtrack.ru/v1/API_КЛЮЧ/my_bot_was_stopped

  • Параметры запроса:

НазваниеТипОписание
user_idstringID пользователя, который заблокировал бота
dateint(optional) Дата события в формате unixtime.
  • Пример тела запроса:
{
  "user_id":"123456789"
}

Проверка подключения​

подсказка

Для проверки работоспособности интеграции используйте нашу 🔗 страницу проверки.

  • Введите ваш API-ключ (полученный на шаге 1) и проверьте последние 100 запросов.

Как получить API ключ.

  • Убедитесь, что ваш бот успешно передаёт события старта и блокировки, а сервис "Откуда Подписки" принимает их без ошибок. Статус обработки событий должен быть 0.

Настройка передачи глубоких целей (метод send_reach_goal)​

Глубокие цели — это любые значимые действия пользователя после старта бота: посмотрел видео, прошел тест, оставил заявку, совершил покупку. Отслеживание таких целей позволяет оптимизировать рекламу на самые важные для бизнеса события.

Как это работает​

В конструкторах ботов (SaleBot, BotHelp и др.) для передачи глубоких целей обычно используется шаг "Внешний запрос" или "Отправить вебхук". В этом шаге прописывается отправка запроса с двумя полями: ID пользователя (user_id) и идентификатор цели (target). Подробнее об этом можно посмотреть в 📘 инструкции по глубоким целям.

В самописном боте вам нужно сделать то же самое — отправить HTTP POST-запрос к нашему API в момент, когда пользователь совершает целевое действие, с теми же двумя полями: user_id и target.

Наш сервис автоматически определяет, откуда пришел этот пользователь (из Яндекс.Директ, VK, Facebook/Instagram или Google). Если пользователь пришел из Яндекс.Директ, цель, которую вы указали в запросе, прокидывается в Яндекс.Метрику. Если из VK — в VK Рекламу, и так далее.

подсказка

Цель можно передавать в течение 21 дня с момента старта бота пользователем.

Настройка запроса​

  • URL для запроса:
https://bot-api.tgtrack.ru/v1/API_КЛЮЧ/send_reach_goal
подсказка

Замените API_КЛЮЧ в ссылке на ваш собственный API ключ, полученный от бота «Откуда Подписки» на 📘 шаге 1.

Метод HTTP-запроса: POST

Заголовки запроса:

  • Content-Type: application/json

Тело запроса (JSON) — два обязательных поля:

НазваниеТипОписание
user_idstringID пользователя в Телеграм, с которым связано событие. Обычно это message.from.id или callback_query.from.id из объекта обновления Telegram
targetstringИдентификатор вашей глубокой цели. Это название события, которое будет передано в рекламную систему. Например: "userDidSharePhone", "testCompleted", "webinarRegistered"

Пример запроса:

{
  "user_id": "987654321",
  "target": "userDidSharePhone"
}

Создание цели в рекламной системе​

После настройки передачи глубоких целей из бота, необходимо создать соответствующую цель в вашей рекламной системе:

  • Яндекс.Метрика: Создайте цель с идентификатором, который совпадает со значением target в вашем запросе. Например, если вы отправляете "target": "userDidSharePhone", создайте цель с идентификатором userDidSharePhone в Метрике. Это обязательно нужно сделать, чтобы цель передавалась корректно.
  • VK Реклама, Facebook/Instagram, Google: Аналогично создайте цели с соответствующими идентификаторами.
подсказка

Для передачи данных по глубокой цели из вашего бота в рекламную систему после настройки интеграции, нужно сделать подключение к рекламной системе по инструкции: 📘 Яндекс Директ, 📘 VK Реклама, 📘 Facebook/Instagram, 📘 Google.

Обработка ошибок и коды ответов​

При интеграции важно понимать, как наш API реагирует на ваши запросы. Это поможет вам быстро находить и устранять возможные проблемы.

При успешном выполнении запроса наш API вернет HTTP-статус 200. Код ошибки 0.

Если в процессе обработки запроса возникнет какая-либо проблема, API вернет один из следующих кодов ошибки. В таблице ниже приведена их расшифровка.

Код ошибкиКороткое описание (англ)Полное описание (рус)
400Bad requestЗапрос содержит синтаксические ошибки или недостаточные данные.
401Invalid tokenТокен аутентификации не верен или отсутствует. Доступ к ресурсу запрещен.
402Token expiredТокен аутентификации истек. Необходимо повторно аутентифицироваться.
403ForbiddenУ вас нет достаточных прав для выполнения этого действия.
404Method not foundЗапрашиваемый метод не найден. Проверьте URL и метод запроса.
405Resource not foundЗапрашиваемый ресурс не существует.
409Data conflictПроизошел конфликт данных, например, попытка создать дублирующую запись.
415Unsupported media typeЗапрашиваемый тип данных не поддерживается сервером.
422Unprocessable entityДанные запроса не прошли валидацию. Проверьте корректность передаваемых данных.
429Too many requestsПревышен лимит запросов. Попробуйте повторить запрос позже.
500Internal server errorПроизошла внутренняя ошибка сервера. Повторите попытку позже.
503Service unavailableСервис временно недоступен. Попробуйте повторить запрос позже.

Полная техническая документация В данной инструкции мы разобрали основные сценарии интеграции. Если вам требуется углубленное техническое описание всех доступных методов, параметров, типов данных и архитектуры API, можете обратиться к нашей полной инструкции.