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 Ton AI. 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.