api-integration

API 集成

帮助开发者从“我想与 X 集成”开始，获取编写代码所需的一切。

前提条件 — MCP 连接（请先阅读）

此技能需要 Meta Social Technologies MCP 服务 devtools（https://mcp.facebook.com/devtools，streamable-http）。插件安装包包含该服务；仅安装技能（例如使用 npx skills add）则不包含（设置说明）。

如果 mcp__devtools__* 工具不可用，请停止。 不要编造工具输出，包括第 1 步中的跟踪调用。请让用户添加该服务并完成 OAuth 流程（绝不要索要访问令牌），然后继续。

工作流

1. 开始跟踪。 在进行任何其他工作之前，调用 devtools_skill_invocation，并设置 action 为 start、skill_name 为 api-integration。在后续步骤的每次 devtools_* 工具调用中，都传入 skill_name api-integration。

2. 确定集成需求。 如果用户尚未说明清楚，询问他们想构建什么。常见集成包括：

   • WhatsApp Business API（发送／接收消息、模板、媒体）
   • Instagram Graph API（发布内容、查看数据洞察、管理评论）
   • Messenger Platform（聊天机器人、发送 API、webhook）
   • Pages API（发布内容、查看数据洞察、管理主页）
   • Marketing API（创建广告系列、管理广告、查看分析数据）
   • 使用 Facebook 登录／使用 Instagram 登录
   • Facebook Login for Business

3. 研究集成。 运行多次搜索，以全面了解情况。不要只做一次搜索 — 通过多层查询覆盖所有方面：

   搜索 1 — 概览和入门：

   • 使用 devtools_discovery → search_docs，搜索产品名称加上“getting started”或“overview”
   • 例如：“WhatsApp Business API getting started”

   搜索 2 — 身份验证和访问令牌：

   • 使用 devtools_discovery → search_docs 搜索身份验证要求
   • 例如：“WhatsApp Business API access token authentication”

   搜索 3 — 所需权限和应用审核：

   • 使用 devtools_discovery → search_docs 搜索权限
   • 例如：“WhatsApp Business API permissions”
   • 如果用户提供了 app_id，也要检查应用：使用 devtools_app_review → requirements 和 privileges

   搜索 4 — 核心 API 端点：

   • 使用 devtools_discovery → search_docs 搜索用户需要的具体操作
   • 例如：“WhatsApp send message API”或“Instagram publish media API”

   搜索 5 — Webhook（如适用）：

   • 使用 devtools_discovery → search_docs 搜索 webhook 设置
   • 例如：“WhatsApp webhooks setup”

   搜索 6 — 速率限制和配额：

   • 使用 devtools_discovery → search_docs 搜索产品特定的速率限制和吞吐量等级
   • 例如：“WhatsApp Business API rate limits messaging tiers”或“Instagram API rate limits”

   搜索 7 — 代码示例和 SDK：

   • 使用 devtools_discovery → search_docs 搜索 SDK、客户端库或代码示例
   • 优先尝试产品特定的查询：“WhatsApp Business Platform Node.js”或“Instagram Graph API Python”
   • 如果没有找到 SDK 结果，搜索“Graph API client library”或该产品的快速入门指南
   • 最后可根据搜索 4 中的端点文档构建示例

   为提高速度，并行运行搜索 1–5。如有需要，再运行搜索 6–7。将 max_results 设为 10，并通过 offset 翻页以获取全面结果。如果初始结果范围太广或遗漏了关键主题，请调整查询。

4. 检查应用是否就绪（如果用户已有应用）：

   • 如果用户通过名称提到了应用（或不确定其 ID），先通过 devtools_app_list（action list）将其解析为 app_id；如果结果不明确，请展示候选项（名称、ID、查看者角色），并让用户选择
   • 使用 devtools_app → basic_settings 确认应用类型和状态
   • 使用 devtools_app_review → privileges 查看已获批准的权限
   • 使用 devtools_app_review → requirements 查看所需条件

5. 综合编写集成指南。 从搜索结果中提取关键信息——不要直接倾倒原始结果。将发现整理成可执行的文档：

   指南格式

   概览

   • API 的用途，以及用户可以用它构建什么
   • 官方产品文档链接

   前提条件

   • Meta 开发者账号
   • 所需的应用类型（Business、Consumer 等）
   • 产品特定的前提条件（例如，WhatsApp Business 账号、Facebook 专页）

   身份验证

   • 所需的令牌类型（用户、专页、系统用户等）
   • 生成令牌的方法
   • 所需的令牌权限／范围
   • 令牌过期与刷新流程

   所需权限

   • 列出所需的各项权限及其授予的权限
   • 哪些权限需要应用审核，哪些会自动批准
   • 如果提供了 app_id：哪些权限已获授，哪些仍需申请

   设置步骤

   • 从零开始到首次 API 调用的分步说明
   • 如果集成需要 Webhook，请包括 Webhook 设置

   关键 API 端点

   • 每个端点包括：方法、URL 模式、关键参数、响应示例
   • 聚焦于用户的需求，不要罗列所有端点

   代码示例

   • 使用用户偏好的语言编写可运行的入门示例
   • 包括身份验证、基本 API 调用和错误处理
   • 如果有官方 SDK，则使用官方 SDK；否则使用原始 HTTP（curl/fetch）
   • 如果集成基于 Webhook，则包括 Webhook 处理程序代码

   速率限制与配额

   • 产品特定的速率限制和吞吐量层级（例如，WhatsApp 消息层级：1K/10K/100K/无限）
   • 适用时列出各端点的速率限制
   • 建议使用 /api-health 持续监控

   常见问题

   • 文档指出的产品特定注意事项
   • 权限错误、令牌类型混淆、Webhook 验证问题

6. 提供后续步骤：

   • 如果权限需要应用审核，使用 /app-review-prep
   • 如果集成使用 Webhook，使用 /webhook-setup
   • 集成上线后，使用 /api-health 监控使用情况

7. 结束跟踪。 完成上述所有步骤后，调用 devtools_skill_invocation，并将 action 设为 end，将 skill_name 设为 api-integration。

提示

• 始终使用不同的查询多次搜索。单次搜索很少能同时涵盖身份验证、权限、端点和示例。
• 代码示例优先使用用户指定的语言／框架。若未指定，默认使用 Node.js/JavaScript。
• 如果用户提供了 app_id，请将其当前权限与集成所需权限进行对照，以节省用户时间。
• 某些集成（WhatsApp、Instagram）需要 Business 类型的应用。如果用户的应用类型不符，请尽早指出。
• 基于 Webhook 的集成（Messenger、WhatsApp）没有回调 URL 就无法运行。请主动建议使用 /webhook-setup。