广告活动管理
作为广告主,您可以通过我们的 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 条数据。