HTTP API

Используйте HTTP API для отправки событий напрямую из Telegram Mini App или сервера.

Telegram WebApp / Mini App

Основной endpoint для приложений на базе Telegram Mini App. Аутентификация происходит через initData из Telegram WebApp SDK — Metriox верифицирует подпись с помощью алгоритма Ed25519.

Endpoint

POST https://ingest.metriox.com/telegram/webapp

Структура запроса

{
  "projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "auth": {
    "initData": "<window.Telegram.WebApp.initData>"
  },
  "events": [
    {
      "eventId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "eventName": "button_click",
      "eventDate": "2026-04-26T10:00:00Z",
      "eventOrigin": "WebApp",
      "eventType": "Custom",
      "propsString": {
        "button_name": "checkout",
        "plan": "premium"
      },
      "propsLong": {
        "price": 299
      },
      "propsFloat": {
        "rating": 4.5
      },
      "propsBool": {
        "is_trial": false
      }
    }
  ]
}

Поля запроса

Поле	Тип	Описание
projectId	UUID	ID проекта из настроек Metriox
botId	UUID	ID бота из настроек Metriox
auth.initData	string	Строка initData из window.Telegram.WebApp.initData
events	array	Список событий (максимум 1000 за запрос)

Поля события

Поле	Обязательное	Тип	Описание
eventId	✅	UUID	Уникальный ID события (для дедупликации)
eventName	✅	string	Название события
eventDate	✅	ISO 8601	Дата и время события
eventOrigin	✅	string	Источник события (например, "WebApp")
eventType	✅	string	Тип события (например, "Custom")
text	❌	string	Текстовое содержимое (опционально)
platformUserId	❌	string	Telegram ID пользователя (определяется автоматически из initData)
propsString	❌	{key: string}	Строковые свойства события
propsLong	❌	{key: number}	Целочисленные свойства
propsFloat	❌	{key: number}	Числа с плавающей запятой
propsBool	❌	{key: boolean}	Булевы свойства

Разделение props по типам

В отличие от flat props: {}, Metriox использует раздельные поля для каждого типа данных. Это позволяет использовать числовые операторы сравнения (>, <) в фильтрах.

SDK делает это автоматически.

Ответ

202 Accepted:

{
  "notConsumedDuplicated": 0,
  "moreEventPropertiesFilledThanAllowed": 0
}

Поле	Описание
notConsumedDuplicated	Количество событий, отклонённых как дубликаты (по eventId)
moreEventPropertiesFilledThanAllowed	Количество событий, превысивших лимит свойств

Пример на JavaScript

async function trackEvent(eventName, props = {}) {
  const initData = window.Telegram.WebApp.initData;

  const propsString = {};
  const propsLong = {};
  const propsFloat = {};
  const propsBool = {};

  for (const [key, value] of Object.entries(props)) {
    if (typeof value === "string") propsString[key] = value;
    else if (typeof value === "boolean") propsBool[key] = value;
    else if (Number.isInteger(value)) propsLong[key] = value;
    else if (typeof value === "number") propsFloat[key] = value;
  }

  await fetch("https://ingest.metriox.com/telegram/webapp", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      projectId: "YOUR_PROJECT_ID",
      botId: "YOUR_BOT_ID",
      auth: { initData },
      events: [
        {
          eventId: crypto.randomUUID(),
          eventName,
          eventDate: new Date().toISOString(),
          eventOrigin: "WebApp",
          eventType: "Custom",
          propsString,
          propsLong,
          propsFloat,
          propsBool,
        },
      ],
    }),
  });
}

// Использование
trackEvent("button_click", {
  button_name: "checkout",
  price: 299,
  is_trial: false,
});

SDK

Для удобства используйте JavaScript SDK — он автоматически разделяет свойства по типам и управляет очередью событий.

---

Коды ответов

Код	Описание
202	Accepted — события приняты
400	Bad Request — ошибка в структуре запроса
401	Unauthorized — невалидный initData
500	Server Error — попробуйте позже

---

Что дальше?

• SDK — рекомендуемый способ интеграции
• События — структура событий
• Типы данных — какие типы свойств поддерживаются