Registration

Before using the ad feature, please complete the registration.

Create Platform

A Platform represents your APP or Website. After creating a Platform, it needs to be reviewed by Ton AI. Once approved, you can become a traffic owner for Ton AI.

create_platform

• App name: Your APP's name
• Telegram direct link: Direct link to your Telegram app
• Web app URL: Your application's URL

Info

App owners can obtain the Telegram direct link through BotFather using the command /myapps.

Prohibition of Gambling Ads

To request disabling gambling ads on your site, contact us via the Telegram account @Ton_AI_Admin.

Create Block

A Block represents an ad slot. You can create multiple ad slots to compare the effectiveness of different placements.

create_block

• Name: Name of the Block
• Reward Webhook URL: After a user clicks on an ad (when the ad system registers a click event), Ton AI will send a request to this URL for rewarding mechanisms.

Tips

If you want to display multiple ads on your site, we recommend creating multiple Blocks to compare the conversion effectiveness of each.

Moderation

Each Platform needs to go through moderation by Ton AI. After approval, you can become a traffic owner for Ton AI.

Tips

Before approval, only test ads will be available. Approved platforms can access official ads.

Get BlockId

On the Platform details page, you can view information for each Block. There is a BlockId column with a copy button next to it. Click to copy it.

Reward Webhook

After a user clicks an ad (when a click event is registered), Ton AI will send a request to this URL for rewarding mechanisms.

Request Method

POST

Request Parameters

Parameter	Location	Type	Description
adBlockId	query	string	Ad slot ID, obtained from Platform -> Block -> ID
openId	query	string	Unique user ID, e.g., telegramUserId
type	query	string	Type corresponding to openId, currently only 'telegram' is supported
campaignId	query	string	Campaign ID
x-api-key	header	string	Your account's App Key; verify this Key to prevent forgery
eventType	query	string	Event type: supports click, complete, conversion
eventId	query	string	Event ID, used for idempotency handling

Note that eventType can be:

• click: User clicked the ad (note: triggering the click event will not lead to a complete event)
• complete: User watched the ad for 15 seconds (without clicking)
• conversion: User navigated to the advertiser's page (in most cases, you can ignore this event)

You can decide which events to reward based on your product requirements.

If watching the ad is enough for a reward, handle it as follows:

if (eventType === 'complete' || eventType === 'click') {
    // Grant reward
}

If users must click the ad for a reward, handle it as follows:

if (eventType === 'click') {
    // Grant reward
}

Notes

• The system may request the Reward Webhook multiple times; ensure your logic is idempotent, using eventId to determine idempotency.
• Verify the App Key to prevent forgery.