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
• Create Ad Campaign API
  • Request Method
  • Request Parameters
  • Complete Request Example
• Update Ad Campaign Status API
  • Request Method
  • Request Parameters
  • Complete Request Example
• Query Ad Campaign List API
  • Request Method
  • Request Parameters
  • Complete Request Example
  • Response Explanation
• Query Ad Campaign Details API
  • Request Method
  • Request Parameters
  • Complete Request Example
• Important Notes

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

1. All required fields must be correctly filled when creating an ad campaign.
2. Status updates can only be applied to existing campaigns.
3. All amounts are in USDT.
4. Campaign list supports pagination, returning up to 100 items per page.