获取评论列表
您可以使用本接口获取广告账户所发视频广告下的评论。
您需设置搜索值及想要获取评论的时间区间。本接口可返回导流广告以及Spark Ads的评论。
v1.2与v1.3版本对比
以下表格概括了 v1.2与v1.3接口的变化。
``xtable
|变化内容{30%}|v1.2{35%}|v1.3{35%}|
|---|---|---|
|接口路径| /v1.2/comment/list/|/v1.3/comment/list/|
|请求参数类型|advertiser_id: number|advertiser_id: string|
|返回参数名称 |is_top<br>list|is_pinned<br>comments|
|返回参数类型 |comment_id: number<br>original_comment_id: number<br>campaign_id: number<br>adgroup_id: number<br>ad_id: number|comment_id: string<br>original_comment_id: string<br>campaign_id: string<br>adgroup_id: string<br>ad_id: string|
|返回参数名称和类型|app_id: number<br>item_id: number|app: string<br>tiktok_item_id: string|
|新增返回参数|/|video_play_url<br>video_cover_url<br>user_avatar_url<br>user_name<br>user_id`|
## 请求
**地址**
https://business-api.tiktok.com/open_api/v1.3/comment/list/
**方法** GET
**Header**
```xtable
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|Access-Token {必填}|string|授权访问令牌。可以通过[获取访问令牌](https://ads.tiktok.com/marketing_api/docs?id=1738373164380162)接口获取。|
参数
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|advertiser_id {必填}|string| 广告主 ID。 |
|comment_type |string[]| 评论类型。<br><br>枚举值：全部 `ALL`，原始评论 `COMMENT`，回复评论 `REPLY`。<br><br>默认值：`["ALL"]`。|
|search_field {必填} |string| 搜索字段。<br><br>枚举值：<ul><li>`ADGROUP_ID`：通过广告组 ID 筛选。</li></ul> |
|search_value {必填} |string| 搜索值。<br><br>`search_field` 为 `ADGROUP_ID` 时，需通过本字段指定一个广告组 ID。<ul><li>若想获取广告账户中的广告组列表，可使用[/adgroup/get/](1739314558673922.html)。</li></ul><br>示例：`1234567891234567`。 |
|sort_field |string| 排序字段。<br><br>枚举值: 创建时间 `CREATE_TIME`，点赞数 `LIKES`，回复数 `REPLIES`。<br><br>默认值：`CREATE_TIME`|
|sort_type |string| 排序类型。<br><br>枚举值：`ASC` （升序）, `DESC`（降序）。|
|start_time {必填} |string| 请求起始时间。<br><br>格式：`YYYY-MM-DD` 。|
|end_time {必填}|string| 请求结束时间。<br><br>格式：`YYYY-MM-DD`。 |
|page_size |number| 分页大小。<br><br>默认值：10。<br><br>取值范围：1-100。|
|page |number| 当前页数。<br><br>默认值：1。<br><br>取值范围：≥ 1。|
示例
(code curl http)
curl --get -H "Access-Token:xxx" \
--data-urlencode "advertiser_id=ADVERTISER_ID" \
--data-urlencode "start_time=START_TIME" \
--data-urlencode "end_time=END_TIME" \
--data-urlencode "comment_type=[\"comment_type\"]" \
--data-urlencode "page_size=PAGE_SIZE" \
--data-urlencode "page=PAGE" \
--data-urlencode "search_value=SEARCH_VALUE" \
--data-urlencode "search_field=SEARCH_FIELD" \
--data-urlencode "sort_field=SORT_FIELD" \
--data-urlencode "sort_by_asc=SORT_BY_ASC" \
--data-urlencode "comment_status=[\"COMMENT_STATUS\"]" \
https://business-api.tiktok.com/open_api/v1.3/comment/list/
(/code)
返回
|字段{30%}|类型{15%}|描述{55%}|
|---|---|---|
|code |number|返回码，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|message |string|返回信息，详见[附录-返回码](https://ads.tiktok.com/marketing_api/docs?id=1737172488964097)。|
|data |object|返回数据。 |
#|comments|object[]| 评论列表。 |
##|comment_id |string| 评论 ID。 |
##|app|string| 应用 ID。 |
##|content |string| 评论内容。 |
##|likes |number| 点赞数。 |
##|replies |number| 回复数。 |
##|comment_type |string| 评论类型。枚举值：原始评论 `COMMENT`，回复评论 `REPLY`。 |
##|original_comment_id |string| 原始评论ID。当 `comment_type`=`REPLY` 时有值。 |
##|comment_status |string| 评论状态。枚举值: 隐藏 `HIDDEN`，公开 `PUBLIC`。 |
##|hit_blockedword |boolean| 是否命中屏蔽词。 |
##|ad_text |string| 广告标题。 |
##|create_time |string| 评论创建时间。 |
##|campaign_id |string| 评论所属推广系列 ID。 |
##|campaign_name |string| 评论所属推广系列名称。 |
##|adgroup_id |string| 评论所属广告组 ID。 |
##|adgroup_name |string| 评论所属广告组名称。 |
##|ad_id|string| 评论所属广告 ID。 |
##|ad_name |string| 评论所属广告名称。 |
##|tiktok_item_id|string|TikTok视频 ID。|
##|identity_id |string|认证身份ID，当使用Spark Ads(`tiktok_item_id`)时必填。如果您不使用Spark Ads，我们仍然强烈建议传入 `ideneity_id` 和 `identity_type` (`CUSTOMIZED_USER`类型)，以便更好地管理广告信息。|
##|identity_type |string|认证身份类型，当使用Spark Ads(`tiktok_item_id`)时必填。枚举值：`CUSTOMIZED_USER` (自定义用户）， `TT_USER` (TikTok用户）。关于认证身份的更多信息，请访问[认证身份](https://ads.tiktok.com/marketing_api/docs?id=1738958351620097)。|
##|is_pinned|boolean| 评论是否置顶。|
##|can_delete|boolean|评论是否可删除。|
##|is_auth_ttba|boolean|用户是否已关联TTBA账户。|
##|is_auth_comment_manage_scope|boolean|用户是否有评论管理权限。|
##|video_play_url|string|视频播放 URL。|
##|video_cover_url|string|视频封面 URL。|
##|user_avatar_url|string|用户头像 URL。|
##|user_name|string|用户名。|
##| user_id | string | 发表评论的 TikTok 用户的 ID。<br> <br>示例： `"6123456789123456789"`。|
#|page_info |object| 分页信息。 |
##|page |number| 当前页数。 |
##|page_size |number| 分页大小。 |
##|total_number |number| 总数。 |
##|total_page |number| 总页数。 |
|request_id |string|请求的日志id，唯一标识一个请求。 |
示例
(code Success-Response http)
HTTPS/1.1 200 OK
{
"code": 0,
"message": "OK",
"request_id": "202105210639490102360430824C1AE673",
"data": {
"comments": [
{
"likes": 0,
"create_time": "2021-01-14 07:04:16 +0000 UTC",
"comment_type": "COMMENT",
"hit_blockedword": false,
"ad_text": "",
"campaign_name": "Bytedance_3006_JP_JA_IOS/AND_1123_dogfood",
"adgroup_name": "Ad Group20201123093958",
"ad_id": "1684147917059121",
"replies": 0,
"comment_status": "PUBLIC",
"original_comment_id": null,
"campaign_id": "1684147923311617",
"adgroup_id": "1684147923311633",
"ad_name": "Ad Name20201123094902",
"comment_id": "6917508027378253825",
"content": "Another creative",
"app": null
},
{
"likes": 0,
"create_time": "2021-01-14 05:54:24 +0000 UTC",
"comment_type": "REPLY",
"hit_blockedword": false,
"ad_text": "",
"campaign_name": "Bytedance_3006_JP_JA_IOS/AND_1123_dogfood",
"adgroup_name": "Ad Group20201123093958",
"ad_id": "1684147917057073",
"replies": 0,
"comment_status": "PUBLIC",
"original_comment_id": "6917441294860550145",
"campaign_id": "1684147923311617",
"adgroup_id": "1684147923311633",
"ad_name": "Creative award~~~",
"comment_id": "6917490050552823810",
"content": "hsbbdbd@user285",
"app": null
},
],
"page_info": {
"total_number": 2,
"page_size": 10,
"page": 1,
"total_page": 1
}
}
}
(/code);