> 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>value_num</code>)</td><td>Единица измерения значения. До 3 символов — например <code>RUB</code>, <code>USD</code>, <code>kg</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` — нет (или наоборот не указан `value_num`, но указан длинный `unit`), запрос будет отклонён с ошибкой `400`.

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

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

{% 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>value_num</code>, но <code>unit</code> не указан</td><td>Добавьте <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>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": "unit is missing"
}
```

{% endcode %}