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
- Ensure that this API is called only when the user has actually completed the conversion action.
- If network problems cause a reporting failure, you may retry shortly, but avoid excessive retries.
- The telegramUserId should be the user's unique Telegram ID; do not use alternative identifiers.
- 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.