> For the complete documentation index, see [llms.txt](https://docs.graspil.com/ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graspil.com/ru/api/send-events.md).

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

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

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

### Запрос

{% code overflow="wrap" lineNumbers="true" expandable="true" %}

```html
POST /v1/send-event
```

{% endcode %}

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

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

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

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

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

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

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

{% code overflow="wrap" %}

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

{% endcode %}

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

{% code overflow="wrap" %}

```json
[
  { "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 }
]
```

{% endcode %}

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

{% code overflow="wrap" %}

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

{% endcode %}

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

{% code overflow="wrap" %}

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

{% endcode %}

***

### Ответ

{% code overflow="wrap" %}

```json
{
  "ok": true
}
```

{% endcode %}

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

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

***

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

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

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

{% code overflow="wrap" %}

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

{% endcode %}