Как подключить самописного бота через 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-данными. Этот запрос называется вебхуком.

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

Получите JSON-данные от Telegram — в вашем обработчике вебхука (endpoint, который принимает запросы от Telegram) возьмите весь JSON-объект, который пришел в теле запроса.
Отправьте этот же 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_id`	string	ID пользователя в Telegram, с которым связано событие.
`first_name`	string	Имя пользователя.
`last_name`	string	(optional). Фамилия, если задана.
`username`	string	(optional). Username в телеграм, если известен.
`full_name`	string	(optional) полное имя пользователя Телеграм.
`start_value`	string	(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_id`	string	ID пользователя, который заблокировал бота
`date`	int	(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_id`	string	ID пользователя в Телеграм, с которым связано событие. Обычно это `message.from.id` или `callback_query.from.id` из объекта обновления Telegram
`target`	string	Идентификатор вашей глубокой цели. Это название события, которое будет передано в рекламную систему. Например: `"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 вернет один из следующих кодов ошибки. В таблице ниже приведена их расшифровка.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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