Отправка пользовательских событий

Отправляет в систему произвольное пользовательское событие — например, «оплатил заказ», «прошёл онбординг», «открыл раздел каталога».

Это самый гибкий способ передать событие: у него нет жёсткой привязки к чату/ресурсу (в отличие от send-target) — только имя события и, по желанию, его «стоимость» и категория.

Запрос

POST /v1/send-event

Метод — POST, тело — JSON. Можно передать:

• один объект события, или

• массив объектов, если нужно отправить несколько событий за один запрос.

Параметры события

Параметр	Тип	Обязательный	Описание
event	string	да	Название события. До 250 символов. Придумываете сами — например order_paid, onboarding_completed
user_id	int	да	Telegram ID пользователя, который совершил событие
value_num	number	нет	Числовое значение события — например, сумма заказа или количество. Можно передавать без unit
unit	string	нет (обязателен, если указан unit без value_num — запрос будет отклонён)	Единица измерения значения. До 3 символов — например RUB, USD, kg. Требует, чтобы был указан value_num
value_str	string	нет	Строковое значение события — например, код промоакции или название тарифа. До 250 символов. Хранится отдельно от value_num/unit, можно передавать одновременно с ними
category	string	нет	Произвольная категория события — для группировки в отчётах. До 250 символов
webapp_name	string	нет	Название Mini App, в котором произошло событие (если применимо). До 250 символов
date	string	нет	Дата и время события в формате ISO 8601, например 2026-06-18T10:00:00.000+03:00. Если не передано — используется текущее время на момент получения запроса

value_num можно передать и без unit (например, просто количество или оценку без единицы измерения). А вот unit без value_num — нельзя: единица измерения без значения, к которому она относится, не имеет смысла, запрос будет отклонён с ошибкой 400.

value_num и value_str независимы друг от друга и хранятся в разных полях — можно передать оба сразу, например числовую сумму заказа и текстовый код тарифа в одном событии.

Пример вызова — одно событие

{
  "event": "order_paid",
  "user_id": 123456789,
  "value_num": 1490.50,
  "unit": "RUB",
  "category": "payments"
}

Пример вызова — несколько событий за раз

[
  { "event": "onboarding_completed", "user_id": 123456789 },
  { "event": "order_paid", "user_id": 123456789, "value_num": 1490.5, "unit": "RUB" },
  { "event": "items_viewed", "user_id": 123456789, "value_num": 5 }
]

Пример вызова — строковое значение

{
  "event": "promo_code_applied",
  "user_id": 123456789,
  "value_str": "SUMMER20"
}

Пример вызова — числовое и строковое значение вместе

{
  "event": "order_paid",
  "user_id": 123456789,
  "value_num": 1490.50,
  "unit": "RUB",
  "value_str": "premium_plan"
}

---

Ответ

{
  "ok": true
}

Метод не возвращает идентификатор события или других данных — успешный ответ "ok": true означает, что все переданные события приняты в обработку. Сама обработка (запись в аналитику) происходит асинхронно, чуть позже.

Если в запросе передан массив из нескольких событий и одно из них невалидно — весь запрос будет отклонён с ошибкой, ни одно событие из массива не будет сохранено.

---

Возможные ошибки

Код	Когда возникает	Как исправить
400	Тело запроса — не валидный JSON	Проверьте, что отправляете корректный JSON и заголовок Content-Type: application/json
400	Не передан event	Добавьте поле event
400	event — не строка или длиннее 250 символов	Сократите название события или передайте строку
400	Не передан user_id	Добавьте поле user_id
400	user_id не является числом	Передайте Telegram ID как целое число, без кавычек
400	Указан unit, но value_num не указан	Добавьте value_num, к которому относится единица измерения, либо уберите unit
400	value_num не является числом	Передайте число без кавычек
400	unit длиннее 3 символов	Используйте короткое обозначение единицы измерения (например RUB вместо рубли)
400	value_str — не строка или длиннее 250 символов	Сократите значение или передайте строку
400	category — не строка или длиннее 250 символов	Сократите категорию или передайте строку
400	webapp_name длиннее 250 символов	Сократите название Mini App
400	date указан, но не распознан как дата	Передавайте дату в формате ISO 8601, например 2026-06-18T10:00:00.000+03:00, либо не передавайте поле вообще
401	API-ключ не передан или недействителен	Проверьте заголовок Api-Key / параметр api-key
500	Внутренняя ошибка сервера	Повторите запрос позже; если повторяется — обратитесь в поддержку

Пример ошибки:

{
  "ok": false,
  "error_code": 400,
  "error": "value_num is missing"
}