Registration

Before using advertising features, please complete registration.

Create Platform

A Platform represents your APP or Website.

create_platform

• App name: The name of your APP.
• Telegram direct link: The direct link to your Telegram application.
• Web app url: The URL of your application.

Info

App owners can use the /myapps command in BotFather to get the Telegram direct link.

Create Block

A Block represents an ad space. You can create multiple Blocks to compare the effectiveness at different placements.

create_block

• Name: The name of the Block.
• Reward Webhook URL: When a user clicks on an ad (and the ad system receives the click), Ton AI will send a request to this URL where you can implement reward distribution.

Tips

If you want to show multiple ads on your website, we recommend creating multiple Blocks to compare each Block's conversion effects.

Moderation

Each Platform requires moderation by Ton AI. Only after approval can it become a traffic source for Ton AI.

Tips

Before approval, you can only get test ads. After moderation, you can access live ads.

Get BlockId

On the Platform details page, you can view information for each Block. There's a column with BlockId and a copy button next to it; click to copy.

Reward Webhook

When a user clicks on an ad (and the ad system receives the click), Ton AI sends a request to this URL for reward distribution.

Request Method

POST

Request Parameters

Parameter Name	Position	Type	Description
adBlockId	body	string	Ad space ID, located in Platform -> Block -> ID
openId	body	string	User's unique ID, e.g., telegramUserId
type	body	string	Type corresponding to openId, currently supports 'telegram'
campaignId	body	string	Campaign ID, recommended for idempotency when issuing rewards
x-api-key	header	string	Your account's App Key, validate this Key to prevent forgery
eventType	body	string	Event type, supports click, complete, conversion
eventId	body	string	Event ID
isSupportVerified	body	boolean	Indicates if the current campaign supports strong verification, true means it does
uuid	body	string	Device fingerprint

Note, the value of eventType can be:

• click: User clicked on the ad (Note: triggering a click event won't proceed with a complete event)
• complete: User watched 15 seconds of the ad (did not click)
• conversion: User visited the advertiser's page (usually, you can ignore this event)

You can decide which type of event to use to issue a reward based on your product needs.

If a user should be rewarded after watching the ad, the logic is:

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

If a user must click the ad to get a reward, the logic is:

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

Attention

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