# 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](/supported-events.md)
* `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](/managing-integration.md)

```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>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tganalytics.xyz/api/endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.