广告活动管理

作为广告主，您可以通过我们的 API 管理您的广告活动。本文档涵盖了创建、更新状态和查询广告活动的核心 API。

API 授权

在 HTTP 请求头中添加 x-api-key 字段，值为您的 APP Key。如何获取 APP Key

创建广告活动 API

请求方法

POST https://app.ton.ai/api/v2/openapi/ad/campaign/create

请求参数

请求体应为 JSON 格式，包含以下字段：

{
  // 广告活动名称
  "name": "string", // 必需

  // 广告目标用户配置
  "targeting": { // 必需
    "includedRegions": ["string"], // 可选，广告目标用户包含区域
    "excludedRegions": ["string"], // 可选，广告目标用户剔除区域  
    "includedLanguages": ["string"], // 可选，广告目标用户包含语言
    "excludedLanguages": ["string"], // 可选，广告目标用户剔除语言
    "platform": "string", // 可选，广告目标用户设备，使用All
    "telegramPremium": false, // 可选，广告目标用户是否为TG会员
    "isHighValueUser": false, // 可选，广告目标用户是否是平台高净值用户
    "userLinkedTonWallet": false // 可选，广告目标用户是否绑定了Ton钱包
  },

  // 广告预算配置
  "budget": { // 必需
    "amount": 0, // 必需，广告每日预算
    "total": 0, // 必需，广告总预算
    "strategy": "daily", // 必需，广告预算策略，固定daily
    "startTime": 0, // 必需，广告开始时间，时间戳格式
    "endTime": 0 // 必需，广告结束时间，时间戳格式
  },

  // 广告计费配置
  "bidding": { // 必需
    "billingType": "string", // 必需，广告计费模式，枚举: CPM、CPC
    "costPer": 0 // 必需，广告在billingType下的出价
  },

  // 广告创意对象
  "ad": { // 必需
    "adFormat": "image", // 必需，广告创意对象格式，填充: image
    "popupImage": "string", // 必需，广告创意对象的展示图片
    "icon": "string", // 必需，广告创意对象icon
    "destination": { // 必需，广告创意对象目标信息
      "actionType": "string", // 必需，广告创意对象行为类型
      "url": "string" // 必需，广告创意对象落地URL
    },
    "text": "string", // 必需，广告创意对象文案
    "brandName": "string", // 必需，广告创意品牌名称
    "buttonText": "string" // 必需，广告创意对象按钮文案
  }
}

完整请求示例

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"
    }
}'

成功响应：

{
  "code": 0,
  "message": "success",
  "data": {
    "campaignId": "12345678"
  }
}

更新广告活动状态 API

请求方法

POST https://app.ton.ai/api/v2/openapi/ad/campaign/status

请求参数

请求体：

字段名	类型	是否必需	描述
campaignId	string	是	广告活动 ID
status	string	是	状态枚举 start、paused、end

完整请求示例

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"
}
'

成功响应：

{
  "data": {
      "result": "success"
  },
  "code": 0,
  "message": "success"
}

查询广告活动列表 API

请求方法

GET https://app.ton.ai/api/v2/openapi/ad/campaign/list

请求参数

参数	位置	类型	是否必需	描述
current	query	number	否	页码，默认为 1
pageSize	query	number	否	每页数量，默认为 20

完整请求示例

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'

成功响应：

{
  "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"
}

请求响应说明

参数	类型	描述
userId	string	创建广告的用户ID
id	string	广告活动ID
name	string	广告活动名称
campaignStatus	string	广告状态
impressions	string	广告浏览次数
clicks	string	广告点击次数
billingType	string	广告计费方式
cost	number	广告总花费
ctr	number	广告ctr转化率
cr	number	广告cr转化率

查询广告活动详情 API

请求方法

GET https://app.ton.ai/api/v2/openapi/ad/campaign/detail

请求参数

参数	位置	类型	是否必需	描述
campaignId	query	string	是	广告活动 ID

完整请求示例

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'

成功响应：

{
  "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"
}

重要说明

创建广告活动时需要正确填写所有必填字段。
状态更新只能应用于现有的广告活动。
所有金额均以 USDT 为单位。
广告活动列表支持分页查询，每页最多返回 100 条数据。