What is a Conversion?

A Conversion refers to the transformation of an exchange task into a new user. Project teams aim to gain new users through exchange, and to optimize the results, you need to report these new users to Ads3. This process is known as a Conversion event.

Service Host Address

Testing Environment: https://staging.ton.ai/

Production Environment: https://app.ton.ai/

API for Reporting Conversion Events

Request Method

POST /api/v2/openapi/exchange/event/report/conversion

Request Parameters

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

The request body should be in JSON format, containing the following fields:

Field Name	Type	Required	Description
eventType	string	Yes	Type of event, fixed value "conversion"
eventData	object	Yes	Event data containing specific fields

The eventData object includes the following field:

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

Complete Request Example

Initiate a request:

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/exchange/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 the upload status with a status code of 200. The response format is as follows:

{
  "status": "success"
}

Important Considerations

1. Ensure that this API is called only when the user has actually completed the conversion action.
2. If network problems cause a reporting failure, you may retry shortly, but avoid excessive retries.
3. The telegramUserId should be the user's unique Telegram ID; do not use alternative identifiers.
4. Protect user privacy by transmitting only essential information.

Tips

Implement error handling and retry strategies to ensure that critical conversion event data is successfully reported.