Ad Campaign Management
As an advertiser, you can manage your ad campaigns through our API. This document covers the core APIs for creating, updating status, and querying ad campaigns.
API Authorization
Include the x-api-key
field in the HTTP request header, with your APP Key as the value. How to Get APP Key
Create Ad Campaign API
Request Method
POST https://app.ton.ai/api/v2/openapi/ad/campaign/create
Request Parameters
The request body should be in JSON format with the following fields:
{
// Campaign name
"name": "string", // Required
// Target user configuration
"targeting": { // Required
"includedRegions": ["string"], // Optional, include target regions
"excludedRegions": ["string"], // Optional, exclude target regions
"includedLanguages": ["string"], // Optional, include target languages
"excludedLanguages": ["string"], // Optional, exclude target languages
"platform": "string", // Optional, target user device, use "All"
"telegramPremium": false, // Optional, is user a TG member
"isHighValueUser": false, // Optional, is user a high-value user
"userLinkedTonWallet": false // Optional, is user linked to Ton wallet
},
// Budget configuration
"budget": { // Required
"amount": 0, // Required, daily budget
"total": 0, // Required, total budget
"strategy": "daily", // Required, budget strategy, fixed as "daily"
"startTime": 0, // Required, start time in timestamp
"endTime": 0 // Required, end time in timestamp
},
// Bidding configuration
"bidding": { // Required
"billingType": "string", // Required, billing mode: CPM, CPC
"costPer": 0 // Required, bid amount under billingType
},
// Ad creative details
"ad": { // Required
"adFormat": "image", // Required, ad format as "image"
"popupImage": "string", // Required, ad display image
"icon": "string", // Required, ad icon
"destination": { // Required, ad target details
"actionType": "string", // Required, action type
"url": "string" // Required, landing page URL
},
"text": "string", // Required, ad text
"brandName": "string", // Required, brand name
"buttonText": "string" // Required, button text
}
}
Complete Request Example
curl --request POST \
--url https://app.ton.ai/api/v2/openapi/ad/campaign/create \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--data '
{
"name": "Campaign Name",
"targeting": {
"includedRegions": ["Africa", "CIS"],
"excludedRegions": ["Eastern Asia", "Southern Asia"],
"includedLanguages": ["hi"],
"excludedLanguages": ["fr"],
"platform": "All",
"telegramPremium": false,
"isHighValueUser": false,
"userLinkedTonWallet": false
},
"budget": {
"amount": 10,
"total": 200,
"strategy": "daily",
"startTime": 1734364800000,
"endTime": 1735596000000
},
"bidding": {
"billingType": "CPC",
"costPer": 0.01
},
"ad": {
"adFormat": "image",
"popupImage": "https://file.ton.ai/xxxxx",
"icon": "https://file.ton.ai/xxccc",
"destination": {
"actionType": "visit.website",
"url": "https://t.me/MeetMeDatingBot/App"
},
"text": "Join MeetMe",
"brandName": "MeetMe",
"buttonText": "Join Now"
}
}'
Successful response:
{
"code": 0,
"message": "success",
"data": {
"campaignId": "12345678"
}
}
Update Ad Campaign Status API
Request Method
POST https://app.ton.ai/api/v2/openapi/ad/campaign/status
Request Parameters
Request Body:
Field Name | Type | Required | Description |
---|---|---|---|
campaignId | string | Yes | Campaign ID |
status | string | Yes | Status: start, paused, end |
Complete Request Example
curl --request POST \
--url https://app.ton.ai/api/v2/openapi/ad/campaign/status \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-api-key: YOUR_API_KEY_HERE' \
--data '
{
"campaignId": "12345678",
"status": "start"
}
'
Successful response:
{
"data": {
"result": "success"
},
"code": 0,
"message": "success"
}
Query Ad Campaign List API
Request Method
GET https://app.ton.ai/api/v2/openapi/ad/campaign/list
Request Parameters
Parameter | Location | Type | Required | Description |
---|---|---|---|---|
current | query | number | No | Page number, default is 1 |
pageSize | query | number | No | Items per page, default 20 |
Complete Request Example
curl --request GET \
--url 'https://app.ton.ai/api/v2/openapi/ad/campaign/list?current=1&pageSize=10' \
--header 'accept: application/json' \
--header 'x-api-key: YOUR_API_KEY_HERE'
Successful response:
{
"data": {
"campaigns": [
{
"userId": "664f211f8135c",
"id": "xxx",
"name": "ads",
"campaignStatus": "onGoing",
"impressions": 0,
"clicks": 0,
"conversions": 0,
"billingType": "CPC",
"cost": 0,
"ctr": 0,
"cr": 0
}
],
"total": 9,
"current": 1,
"success": true
},
"code": 0,
"message": "success"
}
Response Explanation
Parameter | Type | Description |
---|---|---|
userId | string | User ID who created the ad |
id | string | Campaign ID |
name | string | Campaign name |
campaignStatus | string | Current campaign status |
impressions | string | Number of times the ad was viewed |
clicks | string | Number of times the ad was clicked |
billingType | string | Ad billing method |
cost | number | Total ad cost |
ctr | number | Click-through rate (CTR) |
cr | number | Conversion rate (CR) |
Query Ad Campaign Details API
Request Method
GET https://app.ton.ai/api/v2/openapi/ad/campaign/detail
Request Parameters
Parameter | Location | Type | Required | Description |
---|---|---|---|---|
campaignId | query | string | Yes | Campaign ID |
Complete Request Example
curl --request GET \
--url 'https://app.ton.ai/api/v2/openapi/ad/campaign/detail?campaignId=12345678' \
--header 'accept: application/json' \
--header 'x-api-key: YOUR_API_KEY_HERE'
Successful response:
{
"data": {
"name": "ton ads",
"budget": {
"total": 200,
"strategy": "daily",
"amount": 10,
"startTime": 1734364800000,
"endTime": 1735596000000
},
"targeting": {
"includedLanguages": [
"hi"
],
"excludedLanguages": [
"fr"
],
"includedRegions": [
"Africa",
"CIS"
],
"excludedRegions": [
"Eastern Asia",
"Southern Asia"
],
"platform": "All",
"telegramPremium": false,
"userLinkedWallet": false,
"userWalletHasBalanceOnChain": false,
"userLinkedTonWallet": false,
"isHighValueUser": false
},
"campaignStatus": "onGoing",
"bidding": {
"billingType": "CPC",
"costPer": 0.06
},
"ad": {
"adFormat": "image",
"popupImage": "https://file.p",
"icon": "https://file",
"destination": {
"url": "https://app.ton.ai",
"actionType": "visit.website"
},
"text": "show ad",
"brandName": "ton.ai",
"buttonText": "GO"
}
},
"code": 0,
"message": "success"
}
Important Notes
- All required fields must be correctly filled when creating an ad campaign.
- Status updates can only be applied to existing campaigns.
- All amounts are in USDT.
- Campaign list supports pagination, returning up to 100 items per page.