# Endpoints

## POST /events[^1]

This request is needed to record an event in the database

### Body

The request body may contain an array rather than a single event. The main thing is that all events in the array satisfy the scheme below

#### <mark style="color:red;">Required</mark>

* `user_id`
  * Type: <mark style="color:orange;">number</mark>
  * Description: unique identifier for the user.
* `event_name`
  * Type: <mark style="color:orange;">string</mark>
  * Description: the name of the event from the [supported](https://docs.tganalytics.xyz/supported-events)
* `session_id`
  * Type: <mark style="color:orange;">string</mark> **(must be** [**UUID**](https://github.com/Telegram-Mini-Apps/analytics/blob/master/src/utils/generateUUID.ts)**)**
  * Description: session identifier for tracking user sessions
* `app_name`
  * Type: <mark style="color:orange;">string</mark>&#x20;
  * Description: the name of the application that you specified when creating the token

#### <mark style="color:green;">Optional</mark>

* `is_premium`
  * Type: <mark style="color:orange;">boolean</mark>
  * Description: if the user has a premium account, by default - <mark style="color:orange;">false</mark>
* `is_success`
  * Type: <mark style="color:orange;">boolean</mark>
  * Description: indicates whether a wallet is connected or the transaction was successful, by default - <mark style="color:orange;">false</mark>
* `error_message`
  * Type: <mark style="color:orange;">string</mark>
  * Description: error message if the wallet connection or transaction is unsuccessful
* `error_code`
  * Type: <mark style="color:orange;">number</mark>
  * Description: error code if the wallet connection or transaction is unsuccessful
* `wallet_address`
  * Type: <mark style="color:orange;">string</mark>
  * Description: wallet address involved in the event
* `wallet_type`
  * Type: <mark style="color:orange;">string</mark>
  * Description: type of the wallet
* `wallet_version`
  * Type: <mark style="color:orange;">string</mark>
  * Description: version of the wallet software
* `auth_type`
  * Type: <mark style="color:orange;">enum</mark>(0 - <mark style="color:green;">'ton\_addr'</mark>, 1 - <mark style="color:green;">'ton\_proof'</mark>)
  * Description: type of authorization used
* `valid_until`&#x20;
  * Type: <mark style="color:orange;">string</mark>
  * Description: timestamp until when a transaction offer is valid
* `from`
  * Type: <mark style="color:orange;">string</mark>
  * Description: wallet address initiating the transaction
* `messages`&#x20;
  * Type: <mark style="color:orange;">{ address: string; amount: string }\[]</mark>
  * Description: list of transactions {to, amount} involved in the event
* `custom_data`
  * Type: <mark style="color:orange;">object</mark>
  * Description: object to store custom event details as needed
* `client_timestamp`
  * Type: <mark style="color:orange;">string</mark>
  * Description: the time when the event occurred on the clent
* `platform`
  * Type: <mark style="color:orange;">string</mark>
  * Description: the platform from which the MiniApp was opened
* `locale`
  * Type: <mark style="color:orange;">string</mark>
  * Description: user language code
* `start_param`
  * Type: <mark style="color:orange;">string</mark>
  * Description: tgWebAppStartParam
* `url_referer`
  * Type: <mark style="color:orange;">string</mark>
  * Description: the URL of the web application from which the request was sent
* `scope`
  * Type: <mark style="color:orange;">string</mark>
  * Description: event scope

### Request Body Example\`s:

```json
[
  {
    "event_name": "app-init",
    "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d",
    "user_id": 111111111,
    "app_name": "docs",
    "is_premium": true,
    "platform": "tdesktop",
    "locale": "en",
    "client_timestamp": "1743503599534"
  }
]
```

```json
[
  {
    "event_name": "connection-started",
    "custom_data": {
      "ton_connect_sdk_lib": "3.0.3",
      "ton_connect_ui_lib": "2.0.5"
    },
    "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d",
    "user_id": 111111111,
    "app_name": "docs",
    "is_premium": true,
    "platform": "tdesktop",
    "locale": "en",
    "client_timestamp": "1743503647541"
  }
```

```json
[
  {
    "event_name": "connection-error",
    "is_success": false,
    "error_message": "Connection was cancelled",
    "error_code": null,
    "custom_data": {
      "ton_connect_sdk_lib": "3.0.3",
      "ton_connect_ui_lib": "2.0.5"
    },
    "session_id": "10c574d9-6d2c-4e6d-a141-ce6da141ce6d",
    "user_id": 111111111,
    "app_name": "docs",
    "is_premium": true,
    "platform": "tdesktop",
    "locale": "en",
    "client_timestamp": "1743503683701"
  }
]
```

### Headers

Instead of YOUR\_TOKEN, you need to specify the token received using the [bot](https://docs.tganalytics.xyz/managing-integration)

```json
{
    "TGA-Auth-Token": "YOUR_TOKEN",
    "Content-Type": "application/json"
}
```

### Responses

#### <mark style="background-color:green;">HTTP201</mark>

* Description: the event has been successfully recorded
* Content:&#x20;

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "message": "Success record."
}
</code></pre>

#### <mark style="background-color:orange;">HTTP400</mark>

* Description: the event was not recorded due to server issues
* Content:&#x20;

```json
{
    "message": "Failed to record"
}
```

#### <mark style="background-color:orange;">HTTP400</mark>

* Description:  the token was entered incorrectly or in the wrong format
* Content:

```json
{
    "message": "The token is not specified in the headers or is specified incorrectly."
}
```

#### <mark style="background-color:orange;">HTTP400</mark>

* Description:  the entered token is invalid (was not created through a Data Chief bot)
* Content:

```json
{
    "message": "Token is invalid."
}
```

#### <mark style="background-color:orange;">HTTP400</mark>

* Description: the request body contains the application name that does not match the token
* Content:

```json
{
    "message": "Invalid app_name is specified."
}
```

#### <mark style="background-color:orange;">HTTP400</mark>

* Description: the body specified in the request was not validated (for example, the type of one of the fields does not match)
* Content:

```json
{
    "status": 400,
    "message": "VALIDATION_MISMATCH_REPORT"
}
```

#### <mark style="background-color:orange;">HTTP403</mark>

* Description: an attempt to use the API on a domain name that does not match the token
* Content:

```json
{
    "message": "The domain name does not match."
}
```

#### <mark style="background-color:orange;">HTTP429</mark>

* Description: too many requests from the client in a certain amount of time
* Content:&#x20;

```json
{
    "message": "Too many requests. Try again later."
}
```

[^1]: <https://tganalytics.xyz/events>