业务消息的转化 API

广告主可以使用转化 API 通过单个端点（而非多个来源）向 Meta 发送网站事件、应用事件、实体店事件以及业务消息事件。此集成可以简化广告主的技术堆栈，并将通过使用数据集，在 Meta 事件管理工具中提供更全面的概览。

本文档提供将业务消息事件集成到转化 API 方面的指导。将转化 API 用于业务消息的好处包括（但不限于）以下几点：

直接在广告管理工具报告中查看成效：广告主可以直接查看 Meta 界面中的重要数据（例如购物次数和单次购物费用），无需发起对话，做到轻松了解消息直达广告系列的成效。
简化数据集成：一个 API 即可引入和共享多个消息平台（Messenger、WhatsApp）和渠道（网站、应用、实体店、消息功能）的数据。
改善合作伙伴成效衡量效果：通过广告成效分析 API，直接在合作伙伴面板上实现消息直达广告系列归因。

前提条件

数据集

通过转化 API 发送的业务消息事件必须与数据集关联。

通过数据集，广告主可以将来自网站事件源、应用事件源、实体店事件源和业务消息事件源的事件数据与转化 API 关联，并对这些数据进行管理。数据集显示的事件数据可能会来自您选择设置的以下任意集成：

Meta Pixel 像素代码（网站事件）
应用事件 API（应用事件，包括 iOS 版 Facebook SDK、Android 版 Facebook SDK、移动应用成效衡量合作伙伴 (MMP)）
线下转化 API（用于线下事件的 Meta 旧版 API）

通过数据集，您可以在单个界面中查看所有顾客活动。数据集还有��于您减少在构建和维护多个 API 集成方面所投入的精力。

在事件管理工具中，广告主可以根据自己的初衷，采用不同的选项来创建数据集。您也可以在线下事件集创建期间、通过现有移动应用或在消息事件集创建期间进行关联，在事件管理工具中创建一个全新的数据集。请注意，您需要先将数据集与应用程序绑定，才能向转化 API 发送移动应用事件，而且一个数据集只能绑定一个应用程序。请在此处查看更多详情和说明。

权限

如要以广告主的身份实现直接集成，请按照此处说明操作，了解各项前提条件和权限。
如要实现合作伙伴平台集成：
- 您需要 ads_read、ads_management、pages_messaging、whatsapp_business_messaging、pages_show_list 和 instagram_manage_messages 权限的高级访问级别。
- 您需要广告管理标准访问级别功能。
- 根据不同的事件类型，您需要拥有不同权限的高级访问级别。如果是 Messenger 事件或 WhatsApp 事件，您需要拥有 page_events 权限的高级访问级别；如果是 Instagram Direct 事件，您需要拥有 instagram_manage_events 权限的高级访问级别。

合作伙伴注册

如要以开放平台的形式实现合作伙伴集成，您可以使用企业版 Facebook 登录（推荐）或 Meta 业务插件注册方法。

请参阅业务消息的转化 API 指南，其中包含提供分步说明的集成指南。

将数据集 API 用于 Messenger 和 WhatsApp

数据集 API 用于检索附加到给定公共主页的 dataset_id。该 dataset_id 之后将在转化 API 中使用。如要使用数据集 API，您需要通过企业版 Facebook 登录或 Meta 业务插件要求客户为您的应用授予适用于 Messenger 事件或 WhatsApp 事件的 page_events 权限。

如要检索 dataset_id，您需要向数据集 API 发送 GET 调用，并在其中加入 page_id 和 access_token。请参阅以下调用示例：

https://graph.facebook.com/v16.0/{PAGE_ID}/dataset?access_token={TOKEN}

该响应会是一个编号，表示 dataset_id。通过使用此编号和之前收到的访问口令，您现在便可以调用转化 API 来向 Meta 发送消息事件。

将数据集 API 用于 Instagram

数据集 API 用于检索附加到给定公共主页的 dataset_id。该 dataset_id 之后将在转化 API 中使用。如要使用数据集 API，您需要通过企业版 Facebook 登录或 Meta 业务插件要求客户为您应用授予 instagram_manage_events 权限。

如要检索 dataset_id，您需要向数据集 API 发送 GET 调用，并在其中加入 ig_user_id 和 access_token。以下是调用示例：

https://graph.facebook.com/v16.0/{IG_USER_ID}/dataset?access_token={TOKEN}

该响应会是一个编号，表示 dataset_id。通过使用此编号和之前收到的访问口令，您现在便可以调用转化 API 来向 Meta 发送消息事件。

配置

设置业务消息事件参数

您可以参阅此文档，了解当前可通过转化 API 发送的一系列参数。在发送业务消息事件时，可在不同消息平台的用户数据有效负载中分享以下字段：

平台	参数	描述
Messenger	`page_id`	对于 Messenger 为必要参数与企业关联的 Facebook 公共主页编号。
Messenger	`page_scoped_user_id`	对于 Messenger 为必要参数与公共主页互动的用户由公共主页范围用户编号 (PSID) 进行标识。可以通过此 Webhooks 获取 PSID。
WhatsApp	`page_id`	对于 WhatsApp 为必要参数与 WhatsApp 商家关联的 Facebook 公共主页编号。
WhatsApp	`ctwa_clid`	对于 WhatsApp 为必要参数仅可从 Business API 2.45.1 及更高版本（On-Premises API）的消息 Webhooks 下的 referral 对象或云端 API 中获取 `ctwa_clid`。
Instagram	`ig_account_id`	对于 Instagram 为必要参数与企业关联的 Instagram 账户编号。
Instagram	`ig_sid`	对于 Instagram 为必要参数与 Instagram 互动的用户由 Instagram 范围用户编号 (IGSID) 进行标识。可以通过此 Webhooks 获取 IGSID。

发送事件

如要发送新事件，请使用以下路径向转化 API 发送 POST 请求：

https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}

当您向此连线发出 POST 请求后，Meta 会新建业务消息事件。详情请参阅此开发者文档。

下文概述各参数如何融入有效负载的整体架构中。

对于 Messenger 事件：

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "messenger",
      "user_data": {
        "page_id": <PAGE_ID>,
        "page_scoped_user_id": <PSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

对于 WhatsApp 事件：

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "whatsapp",
      "user_data": {
        "page_id": <PAGE_ID>,
        "ctwa_clid": "ARAkLkA8rmlFeiCktEJQ-QTwRiyYHAFDLMNDBH0CD3qpjd0HR4irJ6LEkR7JwFF4XvnO2E4Nx0-eM-GABDLOPaOdRMv-_zfUQ2a", // <CLICK_TO_WHATSAPP_CLICK_ID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

对于 Instagram 事件：

CTD CAPI 请求示例

POST /{dataset_id}/events

{
  "data": [
    {
      "event_name": "Purchase",
      "event_time": 1675999999,
      "action_source": "business_messaging",
      "messaging_channel": "instagram",
      "user_data": {
        "ig_account_id": <IG_ACCOUNT_ID>,
        "ig_sid": <IGSID>
      },
      "custom_data": {
        "currency": "USD",
        "value": 123
      }
    }
  ],
  "partner_agent": "<PARTNER_NAME>"
}

疑难解决

使用事件��理工具中的测试事件工具进行测试：

前往事件管理工具，选择与公共主页关联的数据集
点击“测试事件”选项卡
选择营销渠道和消息渠道
点击图谱 API 探索工具按钮
图谱 API 探索工具会带有预先填充的有效负载
点击“提交”按钮

视频演示

请观看此视频，了解有关如何实现集成的分步说明。

发生错误

播放视频时出错

了解更多

常见问题

业务消息的转化 API 支持哪些类型的消息事件？

回答：业务消息的转化 API 目前仅支持业务消息的潜客信息提交和购买事件。请注意，消息事件应仅代表消息对话中发生的顾客互动，而不是在其他渠道（例如网站）发生的转化。在集成流程中，您可以通过选择相应的操作来源来轻松区分您的事件。

Meta 建议为不同的转化 API 集成使用同一应用，还是使用不同应用？

回答：建议合作伙伴仅用一个应用，以便 Meta 可以识别合作伙伴发送的所有事件。如果您是已拥有多个应用的合作伙伴，请务必将 partner_agent 设置为分配给您的合作伙伴代理商名称。如果您不知道自己的合作伙伴代理商名称，请联系 Meta 代表。

如果转化发生在消息对话之外（例如，发生在我的网站或应用上），我们如何将事件发送给 Meta？

回答：如果转化发生在消息对话之外，您仍应使用相关的转化 API 产品将该事件发回 Meta。例如，如果转化发生在您的网站上，请使用适用于网站事件的转化 API。如果转化发生在您的应用上，请使用适用于应用事件的转化 API。该事件仍将归因于适用于网站事件的转化 API 的点击编号。可在此处查看参数的完整列表。

转化 API 是否消息直达广告实现优化？

回答：转化 API 仅可对 Messenger 直达广告进行购买优化，目前不适用于 WhatsApp 广告优化。对于 WhatsApp 直达广告，您可以通过优化广告系列来提升对话数量。

我是否可以重复使用业务消息的转化 API 的现有数据集？

回答：可以，我们支持绑定现有数据集，您可以参考可用的选项，确定适合您企业的选项。

如果我现在正在使用适用于网站事件的转化 API，将业务消息添加至同一集成中会对我现有的集成产生干扰吗？

回答：将业务消息添加至您现有的 CAPI 集成中不会产生风险。归因基于公共主页/数据集编号，与应用编号无关。

可将多少个数据集与一个公共主页关联？

回答：您仅可将一个数据集与一个公共主页绑定。

我是否需要先对事件去重，然后再通过业务消息的转化 API 发送事件？

回答：Meta 不会协助处理业务消息的转化 API 的事件去重，所以我们强烈建议广告主先对事件去重，再通过业务消息的转化 API 发送事件。

另请参阅

转化 API 概览
使用转化 API
转化 API 参数
最佳实践
实现 WhatsApp Business API 2.45.1 及更高版本的 WhatsApp Business 开放平台（On Premise或云端 API）
Instagram 消息 API