Telegram-боты

Передавайте данные отправителя из обновления Telegram Bot API в Fingprint, чтобы зарегистрировать визит и получить идентификаторы пользователя и посещения. Затем вы сможете запросить данные этого визита или профиль пользователя со статистикой обращений к вашему проекту.

Интеграция работает на сервере бота через внешний API. Браузерный SDK для этих запросов не требуется.

Подготовьте публичный ключСкопировать ссылку

В разделе API-ключи получите активный публичный ключ проекта. Сохраните его в переменной окружения сервера бота:

FINGPRINT_PUBLIC_KEY=ваш_публичный_ключ

Для регистрации визита достаточно заголовка X-Public-Key. Приватный ключ и подпись X-Signature не нужны. Приватный ключ из той же пары понадобится позже, чтобы запросить данные визита или профиль пользователя. Храните его только на сервере.

Зарегистрируйте визит из сообщенияСкопировать ссылку

В обработчике сообщения возьмите update.message.from и отправьте JSON на POST https://gusyrooms.com/api/v1/visit/telegram. Для другого типа обновления используйте объект from его отправителя, например update.callback_query.from для нажатия кнопки.

Передайте два заголовка:

Обязательны три поля: id — числовой Telegram ID отправителя, is_bot — логическое значение, first_name — имя. Передавайте их с исходными типами из Telegram. В примерах функция принимает данные from и отправляет эти поля в Fingprint:

const publicKey = process.env.FINGPRINT_PUBLIC_KEY

if (!publicKey) {
  throw new Error('Задайте FINGPRINT_PUBLIC_KEY в переменных окружения')
}

async function registerTelegramVisit(from) {
  const body = JSON.stringify({
    from: {
      id: from.id,
      is_bot: from.is_bot,
      first_name: from.first_name,
    },
  })
  const response = await fetch('https://gusyrooms.com/api/v1/visit/telegram', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Public-Key': publicKey,
    },
    body,
  })

  if (!response.ok) {
    throw new Error(`Fingprint: HTTP ${response.status} — ${await response.text()}`)
  }

  return response.json()
}

// Вызов внутри вашего обработчика сообщения Telegram:
const { user, request_id, platform } = await registerTelegramVisit(update.message.from)
console.log({ user, request_id, platform })

Какие поля можно передатьСкопировать ссылку

Тело запроса должно содержать объект from со следующими полями:

Передавайте дополнительные поля, только когда они есть в обновлении. Не передавайте отсутствующие поля как null или пустые строки. Число id и логические значения должны сохранять исходные типы: строки "123456789" и "false" API не примет. Другие поля внутри from API не принимает.

Проверьте результатСкопировать ссылку

При успешной регистрации API вернёт HTTP 200 и три поля:

{
  "user": "3c84645edb66cca42aaa99f8fac73a1ea105",
  "request_id": "704039fa045cb5823aaa77c23852c5a55aec",
  "platform": "tg"
}

Оба идентификатора имеют общий с web-визитами формат. Сохраните их из ответа и передавайте без изменений. Чтобы проверить записанные данные, запросите визит по request_id, как описано ниже.

Если регистрация вернула ошибкуСкопировать ссылку

Ответ с ошибкой содержит поле error. При 422 поле errors содержит ошибки по полям, например from.id или from.first_name.

Получите данные визита или профильСкопировать ссылку

Для этих двух методов используйте публичный ключ, с которым зарегистрировали визит, и приватный ключ из той же пары. Передавайте публичный ключ в X-Public-Key, а подпись тела запроса — в X-Signature. Для каждого запроса заново вычисляйте подпись по правилам авторизации.

Вызывайте отдельные методы с суффиксом /telegram. В них не нужно передавать параметр sdk.

В GET-запросе подпишите пустую строку. В POST-запросе подпишите отправляемое JSON-тело.

Например, после регистрации визита в примере на Node.js запросите его данные. Сохраните приватный ключ в переменной окружения FINGPRINT_PRIVATE_KEY. Код использует publicKey и request_id из примера выше:

const { createHmac } = await import('node:crypto')
const privateKey = process.env.FINGPRINT_PRIVATE_KEY

if (!privateKey) {
  throw new Error('Задайте FINGPRINT_PRIVATE_KEY в переменных окружения')
}

const signature = createHmac('sha256', privateKey).update('').digest('hex')
const response = await fetch(
  `https://gusyrooms.com/api/v1/fingerprint/visit/risk/${encodeURIComponent(request_id)}/telegram`,
  {
    headers: {
      'X-Public-Key': publicKey,
      'X-Signature': signature,
    },
  },
)

if (!response.ok) {
  throw new Error(`Fingprint: HTTP ${response.status} — ${await response.text()}`)
}

const visit = await response.json()
console.log(visit.current_visit)

В ответе метода оценки риска проверьте current_visit.request_id и current_visit.from: они содержат идентификатор посещения и данные отправителя, которые вы передали при регистрации.

Метод /profile возвращает последний визит в latest_visit и статистику в statistics: число посещений visits_count, число разных наборов данных from в data_count, даты первого и последнего визита. Статистика и визиты доступны только для ключа, которым подписан запрос. Если для ключа нет подходящего визита или профиля, API вернёт 404.

Оба метода также возвращают risk.is_bot из переданного from.is_bot и уровень risk.level: high при is_bot: true, иначе no. Эта оценка отражает переданный признак Telegram-бота.