Tencent Ads Management Skill

Core Problems in Tencent Ads Management

When managing Tencent advertising accounts, marketers and developers often face several key pain points: difficulty aggregating cross-account data, where performance metrics for different accounts are siloed, making it hard to get a unified view; complex ad entity configuration, as querying detailed settings for smart delivery projects, standard ads, and creatives (e.g., targeting, bidding, placements) involves cumbersome steps; fragmented management of audiences and keywords, requiring separate API integrations for custom audiences, negative keywords, and bidding terms; and limited operation traceability, lacking structured logs for ad or creative modifications, making it difficult to audit field-level changes for troubleshooting.

These fragmented management needs result in substantial repetitive manual work during daily optimization, data reviews, issue investigation, and strategy adjustments.

How the Skill Works: Core Capabilities and Key Steps

This skill encapsulates a suite of dedicated Node.js scripts (e.g., query-report.mjs, query-adgroups.mjs) to handle the underlying API's complexity uniformly. Agents or developers only need to focus on intent recognition and parameter extraction, without constructing raw API requests directly.

Core Capability Modules

• Reporting & Performance Queries: Using the query-report.mjs script, it supports querying metrics like cost, impressions, clicks, and conversions across dimensions such as ad, creative, region, and age. It handles automatic pagination (fetch_all: true) and sorting.
• Entity Detail & Configuration Retrieval: The query-adgroups.mjs script fetches the complete configuration of an ad or smart delivery project (e.g., targeting, bidding, placements); query-creatives.mjs retrieves creative details and automatically parses component details and preview URLs for a single creative.
• Operation Log Auditing: query-operation-logs.mjs queries operation logs for ad/creative objects, returning before-and-after field change details for each modification, useful for auditing and issue tracking.
• Keyword & Audience Management: A set of scripts (e.g., bidword/add.mjs, audiences/update.mjs) manage bidding terms, negative keywords, and custom audience packs (supporting six types), covering the full CRUD lifecycle.

Key Workflow Example

A typical data query flow follows these steps:
1. Intent Recognition & Routing: Determine if the user request is for reporting/performance data (explicitly mentions metrics like cost, ROI) or entity detail queries (only mentions ad/creative configuration). This decides whether to call query-report.mjs or a detail script.
2. Determine Ad Entity Type: Based on mentions of "smart projects", "standard ads", or unspecified "ads", set the tencent_ads_type parameter to smart, standard, or default all, which directly affects return field naming.
3. Parameter Construction & Field Validation: If requested fields (e.g., report metrics) are not in the common mapping table, you must first query the field dictionary using the --query-fields parameter to get the correct API field name and avoid incorrect guesses.
4. Execution & Result Processing: Call the corresponding script, which automatically handles standard filtering, group_by inference, and data trimming, returning structured results.

Applicable Boundaries and Important Notes

• API Dependency: This skill is entirely based on the Tencent Ads Marketing API (api.e.qq.com). All field names and parameter structures are as documented in this skill and may differ from other Tencent open platform documentation—do not confuse them.
• Criticality of Accurate Field Names: Tencent Ads API field names (e.g., report.cost) can differ significantly from common English naming conventions. Guessing field names is strictly prohibited. For non-common fields, you must first use the dictionary query function to obtain the official field name.
• Cross-Platform Calling Rules: Parameter passing differs between Bash and PowerShell. Windows PowerShell must use the --base64 method to pass JSON parameters and strictly follow the Here-String format (newline after @', '@ on its own line), otherwise syntax errors will occur.
• Semantic Clarity of Time Range: The date_range parameter filters the time window for statistical report data, not the creation time of ad entities. To filter "recently created ads," use the created_time field in filtering.
• Automatic Script Optimizations: Scripts handle many optimizations internally. For example, in creative queries, if only one result is returned, it automatically expands component details and preview links; report queries automatically add base filtering conditions. Agents do not need to intervene in these automatic behaviors.