meta-ads

Meta Ads（Marketing API）

从 Meta（Facebook、Instagram、Messenger、Click-to-WhatsApp、Threads）拉取广告成效数据、进行分析，并在获得明确确认后将更改写回（暂停、调整预算、复制、使用图片和文案创建完整广告系列）。

何时查阅此技能

遇到任何关于 Meta 广告成效、创意健康状况、受众／版位组合或广告系列管理的问题时。如果用户问“我的广告效果怎么样”，但没有指定平台，请先询问指的是 Meta 还是 Google，再决定是否默认使用其中一个平台。

执行任何脚本前，先牢记三件事

1. 脚本的运行位置很重要。 脚本会通过开放互联网调用 graph.facebook.com。某些执行环境（包括特定配置下的 Claude Linux 沙盒）会通过代理阻止此端点。如果首次调用时遇到 ProxyError / Tunnel connection failed: 403，请使用用户的主机——macOS、Windows 或 Linux——运行脚本，并使用该机器上的 Python。各操作系统的命令：

• macOS： python3 scripts/auth_check.py，通过 python3 -m pip install --user requests 安装依赖
• Windows： python scripts/auth_check.py（如果 python 不在 PATH 中，则使用 py scripts/auth_check.py），通过 python -m pip install --user requests 安装依赖
• Linux： python3 scripts/auth_check.py，通过 python3 -m pip install --user requests 安装依赖（Debian/Ubuntu 22+ 需添加 --break-system-packages）

脚本本身是纯 Python，仅依赖一个库（requests），不依赖特定的 Shell 或操作系统，因此安装依赖后，在所有系统上的运行方式都相同。

2. WhatsApp 不是独立的广告版位。 Click-to-WhatsApp 广告会投放在 Facebook 和 Instagram 版位上。它们在 Marketing API 中显示为普通广告，具有 destination_type=WHATSAPP，转化事件则位于 actions 下（查找 onsite_conversion.messaging_conversation_started_7d 等）。不要向用户承诺提供“WhatsApp 广告控制面板”——实际上并不存在这样的控制面板。

3. 读取安全，写入有风险。 Insights 端点（GET）是幂等且无害的。暂停、调整预算和复制等操作（POST）会涉及真实资金。references/write-actions.md 中的写入规则不可违反——进行任何写入调用前都要先阅读该文件。

37 个月的数据限制

Meta 的 insights API 只能提供最近 37 个月的数据。早于此时间范围的广告系列都会返回错误 3018，实际上无法查看。如果用户问“我表现最好的广告系列是什么”，而其广告活动早于此时间范围，答案应为“API 无法告知你——请查看 Ads Manager 的归档报告界面”。开始可能失败的查询前，先说明这一点。

首要步骤：检查设置并发现账户

最先执行的三个调用始终相同：

1. python scripts/auth_check.py — 检查令牌是否有效、解析出的身份是什么，以及能看到多少个广告账户。
2. python scripts/list_accounts.py --with-recent-spend — 查看目前实际在投放广告的账户有哪些。（按最近 30 天的支出排序，其次按总支出排序。）据此确定要设为 META_AD_ACCOUNT_ID 的账户。
3. python scripts/list_campaigns.py — 确定正确账户后，查看该账户有哪些广告系列。

如果其中任何一步失败，请停止操作，并按照 references/setup.md 指引用户完成设置。不要自作聪明地猜测凭据。

如何引导用户完成设置（新手指南）

references/setup.md 是一份逐步点击操作的指南。当用户还没有凭据时：

1. 一次只进行一步。 不要把整份文档都发给用户。先询问他们使用的操作系统，然后提供适用于该操作系统的先决条件部分。等他们回复“完成”后再继续。
2. 确认路径选择。 在聊天中与他们一起回答步骤 0 中的决策问题。不要想当然——尤其是“你是否通过 Instagram 推广帖子？”这个问题很容易判断错。
3. 复述他们粘贴的内容。 当他们分享令牌、App ID 或广告账户 ID 时，复述给他们（令牌只显示前 8 个字符），并在继续前确认信息无误。这可以避免最常见的设置错误：把 System User 的 ID 粘贴到应该填写 Ad Account ID 的位置。
4. 继续前先验证。 他们填写 .env 后，立即运行 auth_check.py。在验证返回 ok: true 之前，不要让他们运行分析命令——每个“报告为空”的问题都源于 .env 配置不完整。
5. 每条命令都要匹配他们的操作系统。 如果他们说“我用的是 Windows”，就不要让他们运行 python3，而要告诉他们使用 python 或 py。如果他们说“我用的是 Mac”，就使用 python3。setup.md 中提供了各操作系统对应的命令块；将匹配的部分复制到聊天中。

必需的环境变量（用户在设置期间提供一次）：

• META_ACCESS_TOKEN — 长期有效的用户令牌（路径 B，有效期 60 天）或 System User 令牌（路径 A，永不过期）。请参阅下方的决策树。
• META_AD_ACCOUNT_ID — 默认广告账户，格式为 act_1234567890（脚本接受 --account-id，可在每次调用时覆盖）。
• META_API_VERSION — 默认值为 v25.0（截至 2026 年初的当前版本；预计 2026 年 9 月左右推出 v26.0）。

用户将这些变量写入工作目录中的 .env 文件，或在 shell 中导出。若存在 .env 文件，脚本会自动加载。请参阅 assets/env.template。

路径 A 与路径 B：该选择哪种令牌类型？

这是最常见的失败原因。务必一开始就选对。

以下情况使用路径 A（System User 令牌）：

• 广告在你管理的 Meta Business Manager 中投放。
• 你要分析的广告账户归该 BM 所有。
• 你需要永不过期的令牌。

以下情况使用路径 B（长期有效的用户令牌）：

• 你通过 Instagram 应用推广帖子（这类操作通常会在任何 BM 之外创建个人广告账户；无论授予什么权限，System User 令牌都无法看到这些账户）。
• 你的广告账户关联的是个人 Facebook 个人资料，而不是 BM。
• 你想查看个人 FB 登录可以访问的所有广告账户（通常覆盖范围最广）。

不确定该选哪种？ 从路径 B 开始。它能看到的内容严格包含路径 A 可见的所有内容。确定重要账户后，你可以选择将它们迁入 BM，再切换到路径 A，以便长期使用。

两种路径的完整设置步骤：references/setup.md。

工作流：读取操作

对于任何读取请求，都遵循以下循环：

1. 选择合适的脚本。 不要重复造轮子。随附脚本涵盖了常见情况：

   • auth_check.py — 验证令牌，简要列出可见账户
   • list_accounts.py — 查找所有广告账户、解码状态、显示终身支出和可选的近期支出
   • list_campaigns.py — 列出账户下的广告系列，并提供状态筛选
   • fetch_insights.py — 主力工具。支持日期范围、细分维度（publisher_platform、age、gender、country、placement、device_platform）、层级（account/campaign/adset/ad）和自定义字段列表。调用前先阅读其 --help。
   • creative_fatigue.py — 在广告层级分析频次和 CTR 衰减
   • anomaly_detect.py — 将某个日期范围与此前等长的日期范围进行比较，并标记显著变化
   • exchange_token.py — 仅限路径 B：将短期用户令牌换成有效期为 60 天的长期令牌

   写入脚本（暂停／预算／复制／创建 — 先阅读 write-actions.md）：

   • pause_ad.py — 暂停／恢复单个广告系列、广告组或广告
   • update_budget.py — 修改每日或终身预算，每次调用的安全上限为 2 倍
   • duplicate_ad.py — 将广告、广告组或整个广告系列克隆为新副本
   • create_campaign.py — 根据规范 JSON 创建完整广告系列（广告系列 + 广告组 + 创意 + 广告）。支持上传图片并解析兴趣。参见 references/campaign-creation.md。
   • rollback_creation.py — 使用状态文件暂停或删除 create_campaign.py 运行创建的所有对象

2. 运行脚本并捕获 JSON 输出。 每个脚本都会向 stdout 输出结构化 JSON。不要尝试解析人类可读文本 — 脚本不会输出此类文本。如果用户想保留原始数据，请将输出重定向到文件：python scripts/fetch_insights.py ... > insights.json。

3. 使用分析手册进行分析。 获取数据后，请查阅 references/analysis-playbooks.md，找到相关模式（疲劳、漏斗、受众组合、异常）。手册会说明需要关注的阈值以及建议内容。

4. 使用用户偏好的语言进行呈现。 如果用户用希伯来语提问，请用希伯来语回复。指标名称保留英文（CTR、CPA、ROAS），以便与 Ads Manager 准确对应。如果用户要求提供文档／仪表板，请遵循他们设置的设计系统技能。

工作流：写入操作（暂停、预算、复制）

这些操作具有风险。每次都必须遵循此流程，不得走捷径：

1. 调用前，用通俗语言说明操作及其影响。 例如：“暂停广告 Campaign_v3（ID 120214...）。该广告过去 7 天花费了 ₪47，CTR 为 0.8%。确认吗？”
2. 等待用户在聊天中明确回复 yes／confirm 或对应的本地语言表达。 对话中此前说过的“继续”不算数。每次写入操作都必须单独确认。
3. 默认一次只执行一个操作。 如果用户想批量暂停 12 个广告，请列出编号并通过一条明确消息确认整批操作（“暂停全部 12 个”），但每次调用都要单独记录。
4. 脚本支持试运行时，务必先进行试运行（--dry-run 标志会显示将要进行的更改，但不会调用 API）。
5. 绝不要在一次调用中自动将预算提高超过 +50%。 如果用户想提高到 3 倍，请分步操作，并在每一步都进行确认。无论如何，Meta 的学习阶段在大幅调整预算后都会重置。

完整规则和特殊情况见 references/write-actions.md。调用以下任意脚本前，请先阅读该文件：pause_ad.py、update_budget.py、duplicate_ad.py、create_campaign.py。

工作流：从头创建广告系列

使用 create_campaign.py 根据规格 JSON 一次性构建完整的广告系列树（广告系列 → 广告组 → 创意 → 广告）。适用于 A/B 投放：你希望结构完全一致、命名规范严谨，并且创建历史可审计。

运行脚本前：

1. 检查用户是否有像素。 没有像素 → 强制设置 objective: OUTCOME_TRAFFIC 和 optimization_goal: LINK_CLICKS。不要在无法衡量转化的账户上创建转化广告系列；你付费让 Meta 朝着它永远看不到的事件进行优化。请向用户说明这一点，让他们决定是等像素安装完成，还是直接以流量目标盲投。
2. 检查账户余额。 广告账户的状态码 3（UNSETTLED）表示可以创建对象，但在余额结清前不会投放。不要阻止创建，但要在用户预期产生花费前告知他们。
3. 找到正确的主页和 Instagram 身份。 用户通常拥有多个主页。查询 /me/accounts 和 /act_.../promote_pages，并根据哪个主页投放过他们历史上表现最佳的广告来匹配（获取若干条近期广告，查看 creative.effective_object_story_id，从前缀中确定主页 ID）。
4. 默认将所有内容设为 PAUSED。 创建时，广告系列、广告组和广告都应设为 PAUSED。让用户在 Ads Manager 中检查创意后自行切换为 ACTIVE。这是最后一道安全保障。
5. 始终先进行试运行。 create_campaign.py --spec foo.json --dry-run 会打印完整计划，包括解析后的兴趣 ID、按币种修正后的预算以及定向摘要。用通俗语言向用户说明试运行结果，然后再请求他们使用 --confirm。

根据 write-actions.md，即使用户在同一会话中早些时候已批准计划，使用 --confirm 仍需获得新的明确确认。确认内容必须指明操作（例如“确认创建”或“בצע יצירה”），不能只是笼统地说“ok”。

完整规格格式、字段参考、币种处理、兴趣解析、状态文件和回滚详情：references/campaign-creation.md。

不要使用 create_campaign.py 的情况

• 向现有广告组添加单条广告 — 直接调用广告端点或使用 UI 即可。为单条广告编写规格并运行脚本，属于杀鸡用牛刀。
• 复制表现最佳的广告 — duplicate_ad.py 更快，而且会保留学习信号。
• 动态创意、目录广告、精品栏广告 — v1 不支持。该脚本仅通过 link_data 处理单图链接广告。如有需要，请扩展该脚本或编写一个配套脚本。

脚本已为你处理的注意事项

• 货币最小单位。 Meta 返回的 amount_spent、balance、spend_cap、daily_budget、lifetime_budget 均为最小货币单位（阿哥拉／美分／便士）的字符串。list_accounts.py 和 list_campaigns.py 会将其转换为主要货币单位，并存入 _major 字段或普通十进制字段。零小数位币种（JPY、KRW、VND、ISK、TWD 等）不会进行除法换算。
• 账户状态码。 脚本会将 1→ACTIVE、2→DISABLED、3→UNSETTLED、7→PENDING_RISK_REVIEW 等状态码转换为对应状态。
• 分页。 所有脚本都会通过 meta_client.paginate() 自动分页。
• 速率限制。 meta_client._request() 会在遇到子代码 1487742 / 2446079 / 1487390 时退避并重试。
• 异步洞察数据。 当同步查询可能超时时，fetch_insights.py 会自动回退到异步任务（也可以使用 --async 强制启用）。
• 已删除的广告系列。 请求已删除的广告系列时，Meta 的广告系列端点会返回错误 1815001。脚本的 --status 选项会刻意排除 DELETED。要查看已删除的广告系列，请使用 Ads Manager UI。

捆绑脚本无法处理的事项

• 初始身份验证／令牌生成（手动操作，参见 references/setup.md）。
• Pixel／Conversions API 事件摄取（独立 API）。
• 动态创意／目录／合集广告格式（仅支持单图链接广告）。
• 创建自定义受众（可以引用现有受众，但无法在此创建新受众）。
• 原地编辑已投放的创意（通过 create_campaign.py 创建新创意；编辑现有创意需要使用不同的 API 格式）。

如果用户需要脚本未覆盖的功能，请在可写副本中扩展此技能并重新打包——写入脚本可参考 references/campaign-creation.md 中 create_campaign.py 采用的模式。不要在用户的工作目录中另行创建一次性脚本；应将其整合到技能中，以便下次运行时也能受益。

参考文件

按需阅读，无需一开始全部读完。

• references/setup.md — 一次性设置：Path A 与 Path B 的决策树、如何创建应用、获取令牌、查找账户 ID。用户没有凭据或 auth_check.py 失败时阅读。
• references/insights-fields.md — 字段术语表、细分选项、常见指标定义、注意事项（归因窗口、action_attribution、去重）。构建自定义洞察查询时阅读。
• references/analysis-playbooks.md — 创意疲劳、受众分析、漏斗诊断、异常响应的模式。用户要求分析而非仅获取数据时阅读。
• references/write-actions.md — 进行任何写入调用前必须阅读。确认流程、安全阈值、回滚模式——包括使用 create_campaign.py 前要阅读的广告系列创建部分。
• references/campaign-creation.md — create_campaign.py 的规格格式、字段参考、货币处理、兴趣解析、状态文件和回滚详情。用户要求从头开始投放广告系列、进行 A/B 测试或启动新广告投放时阅读。
• references/troubleshooting.md — 常见故障模式（沙盒代理、SU 令牌无法显示 IG 推广内容、缺少 requests 模块、编码问题、37 个月上限等）。任何脚本返回 ok: false 或出现意外情况时阅读。

扩展到个人用途之外

此技能面向单个用户、一组凭据和少量广告账户构建。多租户／客户代理机构用途（一位操作人员管理数十个客户 BM）需要采用不同的构建方案：

• 按客户存储凭据（而非将所有人的令牌放在一个 .env 文件中）。
• 每位客户都从自己的 BM 签发自己的 System User 令牌。
• 记录每项写入操作的审计日志，包括触发者及操作所针对的账户。

不要尝试将个人版技能改造成多租户用途。应告知用户这需要采用不同的构建方案。