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

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

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

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

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

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

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

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

примечание

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

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

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

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

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

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

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

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

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

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

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

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

подсказка

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

• Метод 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"
}

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

подсказка

Для проверки работоспособности интеграции используйте нашу страницу проверки (https://bot-api.tgtrack.ru/last_events).

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

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

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

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

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

Метод send_reach_goal пересылает достижение цели в рекламную систему, откуда пришел пользователь.

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

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

Например, в вашей воронке есть шаг получения номера телефона. Вы можете передавать в рекламные системы (Яндекс,ФБ,ВК,Google) информацию о тех, кто оставил номер, чтобы реклама обучалась на эти события.

В этом случае метод send_reach_goal пробросит достижение цели в ту рекламную платформу, откуда изначально пришел пользователь. Цель можно передавать в течение 21 дня с момента старта бота.

Название	Тип	Описание
user_id	string	ID пользователя в Телеграм, c которым связано событие в боте
target	string	Идентификатор события в рекламной системе. Достижение этой цели будет передано в Яндекс,ФБ,ВК,Гугл

Пример:

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

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

При интеграции важно понимать, как наш 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	Сервис временно недоступен. Попробуйте повторить запрос позже.