API Ad Integration

If you want to seamlessly integrate ads into your application without obvious pop-ups or banners, you can achieve it through API.

Warning

This method involves a high integration cost. Please use it cautiously and consider using SDK ad integration whenever possible.

This feature is currently in the testing phase, available to a select group of users, and may be removed in future versions.

Tips

Ensure to perform ad retrieval and reporting on the frontend, so the system can access the visiting user's IP for ad region matching.

Prerequisites

Decide where to display the ads. If unsure, check the ad integration examples.
Obtain a BlockId. If you don't have one, refer to Get BlockId.

1. Retrieve Ad API

API Description

This API is used to obtain ad information, which you need to embed into your product.

Tips

In the production environment, an ad will not be shown again to a user within 10 minutes after a click.

This restriction does not apply in test environments.

Tips

It is recommended to fetch multiple ads at once and display them simultaneously to improve click-through rates.

Request Method

GET https://app.ton.ai/api/v2/openapi/matching/ad

Request Parameters

Parameter Name	Location	Type	Required	Description
adBlockId	query	string	Yes	Ad spot ID, obtained from Platform -> Ad Spot -> ID
openId	query	string	Yes	User's unique identifier
type	query	string	Yes	Type corresponding to openId, currently only 'telegram'
limit	query	number	Yes	Limit on number of ads returned at once, must be >0 and <10
x-api-key	header	string	Yes	API Key, How to Get App Key?
debug	header	boolean	No	Returns test ads when debug=true, default is false

Tips

Set debug=false in the production environment.

Response Parsing

Parameter Name	Type	Description
adBlockId	string	Ad spot ID
adId	string	Advertisement ID
campaignId	string	Campaign ID
icon	string	Advertisement icon URL
image	string	Advertisement image URL
text	string	Advertisement text
destination	object	Advertisement target information
destination.actionType	string	Advertisement action type, e.g., 'visit.website'
destination.url	string	Advertisement target URL

Complete Request Example

Execute the following request:

curl --request GET \
     --url 'https://staging.ton.ai/api/v2/openapi/matching/ad?adBlockId=66f65d8b2ec147ec042aa530&openId=16213622061&type=telegram&limit=2' \
     --header 'accept: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90'

A successful response will return a list of ads with a status code of 200.

{
  "data": {
    "msg": "ads success",
    "success": true,
    "ads": [
      {
        "icon": "https://file.pea.ai/ad_avatar_development/664f211f8135c60011c30dab_222777_PEPE-1.png",
        "adBlockId": "66f65d8b2ec147ec042aa530",
        "adId": "66f65baa2ec147ec042aa4a1",
        "campaignId": "66f65baa2ec147ec042aa49f",
        "image": "https://file.pea.ai/ad_development/664f211f8135c60011c30dab_801668_GoPlus.jpg",
        "text": "test ton ai",
        "destination": {
          "actionType": "visit.website",
          "url": "https://app.ton.ai"
        }
      }
    ]
  },
  "code": 0,
  "message": "success"
}

2. Report Click Event API

API Description

This API is used to report a Click event whenever a user interacts with an ad. Publishers need to call this API when a user clicks an ad.

Warning

Do not report fake Click events

Both advertiser and publisher data are reported to the Ads3 platform. Reporting false Click events will result in data discrepancies, and such behavior will lead to penalties.

Request Method

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

Request Parameters

Request parameters should be in JSON format, containing the following fields:

Field Name	Type	Required	Description
eventType	string	Yes	Event type, fixed value "click"
eventData	object	Yes	Event data, containing fields

The eventData object includes:

Field Name	Type	Required	Description
adBlockId	string	Yes	Ad spot ID, obtained from Platform -> Ad Spot -> ID
telegramUserId	string	Yes	User's unique Telegram ID
adId	string	Yes	Ad ID returned by the previous API, representing the clicked advertisement
campaignId	string	Yes	Campaign ID of the clicked advertisement

Complete Request Example

Execute the following request:

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/ad/event/report \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90' \
     --data '
{
  "eventType": "click",
  "eventData": {
    "adBlockId": "66f65d8b2ec147ec042aa530",
    "telegramUserId": "16213622061",
    "adId": "66f65baa2ec147ec042aa4a1",
    "campaignId": "66f65baa2ec147ec042aa49f"
  }
}
'

A successful response will return the ad list data, with a status code of 200.

{
  "data": {
    "status": "success",
    "msg": "report event success"
  },
  "code": 0,
  "message": "success"
}

Points to Note

Only call this API when a user actually clicks on an ad.
Avoid double-reporting the same click event.
Retry shortly if network issues cause failure, but don’t overdo it.
telegramUserId should uniquely identify the user on Telegram; do not use other identifiers.
adId and campaignId should correspond to the actual clicked ad, not other ads.