API Advertising Integration

If you want to seamlessly integrate ads into your app without obvious popups or banners, you can achieve this through API integration.

Warning

This method has a higher integration cost. It's recommended to use SDK integration when possible.

This feature is currently in testing and available only to select users.

Prerequisites

Know where to display ads. If you don't, please refer to Ad integration examples.
Have obtained an ExchangeId. If not, please check Get ExchangeId.

1. Retrieve Ads via API

API Description

This API is used to fetch advertisement information from the exchange. You need to embed the returned ad information into your product.

Tips

In a production environment, ads that users have clicked won't be recommended again. This feature is disabled in the testing environment.

Tips

It's recommended to fetch multiple ads at once to offer users more choices and increase click-through rates.

Request Parameters

Parameter	Location	Type	Required	Description
exchangeCampaignId	query	string	Yes	Exchange advertisement campaign ID, obtainable from the management console exchange section
openId	query	string	Yes	User's unique identifier
type	query	string	Yes	User type, currently only supports 'telegram'
limit	query	number	Yes	Limit for the number of ads returned, must be greater than 0 and less than 10
x-api-key	header	string	Yes	API key, how to get your API key?. The testing environment can use moJHPwHiGpSP7Lrz88xY1IAXXamF90

Response Parameters

Field Name	Type	Required	Description
inExchangeCampaignId	string	Yes	Incoming traffic ID
outExchangeCampaignId	string	Yes	Outgoing traffic ID
icon	string		Ad icon URL
image	string		Ad image URL
text	string		Ad text
destination	object		Ad destination details
destination.actionType	string		Ad action type, e.g., 'visit.website'
destination.url	string		Ad destination URL

Sample Request

Make a request:

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

A successful response will return a list of ad data with a status code of 200. The response format is as follows:

{
  "data": {
    "success": true,
    "exchangeCampaigns": [
      {
        "icon": "https://file.pea.ai/ad_avatar_development/665448d46c9e4700110b1b44_131267_TonAi-black%20bg%20logo-80.jpg",
        "inExchangeCampaignId": "66f65d2d2ec147ec042aa504",
        "outExchangeCampaignId": "66f65ed42ec147ec042aa597",
        "image": "https://file.pea.ai/ad_development/665448d46c9e4700110b1b44_437882_image%20%281%29.png",
        "text": "Welcome to Ads3",
        "destination": {
          "actionType": "visit.website",
          "url": "https://t.me/peaaibot/app"
        }
      },
      {
        "icon": "https://file.pea.ai/ad_avatar_development/66f8f1f363476d0011ed93c3_470779_1111.png",
        "inExchangeCampaignId": "66f8f68d1d2a179b00c0823e",
        "outExchangeCampaignId": "66f65ed42ec147ec042aa597",
        "text": "Click to Earn Bankcoins",
        "destination": {
          "actionType": "visit.website",
          "url": "https://t.me/bankcoins_bot/start?startapp=source-tonai"
        }
      }
    ]
  },
  "code": 0,
  "message": "success"
}

2. Report Click Event API

API Description

This API is for reporting Click events when users click on ads. Partners need to call this API when a user clicks on an ad.

Warning

Do not report false Click events

Data from both advertisers and the exchange will be reported to the Ads3 platform. Reporting false Click events will lead to data discrepancies, and such actions will lead to penalties as detected by the system.

Request Method

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

Request Parameters

Parameter	Location	Type	Required	Description
x-api-key	header	string	Yes	API key, how to get your API key?

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

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

The eventData object includes the following fields:

Field Name	Type	Required	Description
telegramUserId	string	Yes	User's unique Telegram ID
inExchangeCampaignId	string	Yes	Incoming exchange ad campaign ID
outExchangeCampaignId	string	Yes	Outgoing exchange ad campaign ID

Sample Request

Make a request:

curl --request POST \
     --url https://staging.ton.ai/api/v2/openapi/exchange/event/report \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: moJHPwHiGpSP7Lrz88xY1IAXXamF90' \
     --data '
{
  "eventType": "click",
  "eventData": {
    "telegramUserId": "1728125519",
    "inExchangeCampaignId": "66f50be715d2076bd74c7452",
    "outExchangeCampaignId": "66f3969f7fe5f0572809261a"
  }
}
'

A successful response will indicate the event was reported successfully, with a status code of 200.

{
  "status": "success"
}

Important Considerations

Ensure the API is called only when the user actually clicks on an ad.
If network issues cause reporting failures, retry in a short timeframe, but avoid excessive retries.
telegramUserId should be the user's unique Telegram ID, not any other identifier.