Introduction

Besides the default SDK automatic reporting mode, Ton AI also supports multiple reporting methods. You can choose the method that best suits your needs.

Method 1: SDK Reporting for Valid Users

Prerequisites

Please refer to the SDK Installation Guide to complete SDK initialization.

Reporting Method

If you want to manually report valid users when they complete specified actions, you can follow the method below:

import { SendTonAdConversion } from 'ton-ai-sdk'

// Report a Conversion event when the user completes the specified action
if (userHasConverted) {
  SendTonAdConversion()
}

Tips

In the Telegram Mini APP, the SDK will automatically get the current logged-in user's TelegramUserId. Alternatively, you can choose to provide it yourself.

import { SendTonAdConversion } from 'ton-ai-sdk'

const telegramUserId = '1234567890'
SendTonAdConversion(telegramUserId)

The reporting process is quite simple; just call the SendTonAdConversion method when the user completes the designated action.

SDK Reporting for Custom Events

Tips

Coming Soon: This feature will be available soon.

If you're not sure which type of event to use for defining user conversion, you can report custom events:

import { SendTonAdConversion } from 'ton-ai-sdk'

// Report custom events
SendTonAdEvnt('onboard')
SendTonAdEvnt('register')
SendTonAdEvnt('play')
SendTonAdEvnt('payment')
SendTonAdEvnt('withdraw')

Then, when creating a Campaign, you can choose which event to use as the basis for Optimization.

Method 2: Using API to Report Valid Users

If your Mini APP cannot use the SDK to report valid users, you can use the API method instead.

Request Method

POST https://app.ton.ai/api/v2/openapi/ad/event/report/conversion

Request Parameters

Name	Location	Type	Required	Description
x-api-key	header	string	Yes	How to Get APP Key

The request body should be in JSON format and include the following fields:

Field Name	Type	Required	Description
eventType	string	Yes	Event type, fixed value is "conversion"
eventData	object	Yes	Event data, must include the following fields

The eventData object should include the following field:

Field Name	Type	Required	Description
telegramUserId	string	Yes	The unique Telegram ID of the user

Complete Request Example

Make a request:

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/ad/event/report/conversion \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY_HERE' \
     --data '
{
  "eventType": "conversion",
  "eventData": {
    "telegramUserId": "1728125519"
  }
}
'

A successful response will indicate that the upload was successful, with a status code of 200. The response will look like this:

{
  "status": "success"
}

Method 3: Provide API to Verify Users

You can also provide an API for Ton AI to verify if users are valid.

Ton AI will query your API after the user clicks an ad to verify if the user genuinely entered the advertiser's product.

Request Method

GET

Request Parameters

Name	Type	Required	Description
telegram_id	string	Yes	The Telegram ID of the user

Return Value

The return value is of string type, indicating the verification result:

• "true": Verification successful
• "false": Verification failed

Successful Verification Example

curl --location 'https://app.pea.ai/api/v1/common/verify/example/success' \
--header 'Content-Type: application/json' \
--data '{"telegram_id": "123456789"}'

Return result:

"true"

Verification Failure Example

curl --location 'https://app.pea.ai/api/v1/common/verify/example/fail' \
--header 'Content-Type: application/json' \
--data '{"telegram_id": "987654321"}'

Return result:

"false"