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

Как подключить самописного бота через 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_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"
}

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

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

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

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

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

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

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

Пример:

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

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

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