这份文档说明了如何以编程方式获取您企业所发送和接收消息的指标。消息功能成效分析 API 是公共主页成效分析 API 的扩展,可用于获取 Facebook 公共主页的“公共主页成效分析”选项卡中显示的信息。
本指南假设您已经查看 Messenger 开放平台概览,并且已经实现发送和接收消息和通知所需的组件。
要查看您所拥有的或能够在其上执行 ANALYZE
任务的 Facebook 公共主页的指标,您的应用需要:
pages_messaging
pages_read_engagement
pages_show_list
read_insights
要查看非您所拥有的或无法在其上执行 ANALYZE
任务的 Facebook 公共主页的指标,您的应用需要:
ANALYZE
任务的用户请求pages_messaging
pages_read_engagement
pages_show_list
read_insights
要读取一个或多个指标的信息,请将 GET
请求发送至 /PAGE-ID/insights
端点,并将 metric
参数设为一个以英文逗号分隔的待查看指标的清单。
curl -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights ?metric=page_messages_new_conversations_unique,page_messages_blocked_conversations_unique &access_token=PAGE-ACCESS-TOKEN"
成功后,应用会收到以下 JSON 响应:
{ "data": [ { "name": "page_messages_new_conversations_unique", "period": "day", "values": [ { "value": "42", "end_time": "1665175977" }, ] }, { "name": "page_messages_blocked_conversations_unique", "period": "day", "values": [ { "value": "0", "end_time": "1665175977" }, ] } ], }
以下示例查找特定时间段内新独立对话总数的方法是:在我们的 API 调用中,添加 period
参数(将其设为 total_over_range
)以及定义时间范围的两个参数 since
和 until
。
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/ ?metric=page_messages_new_conversations_unique &since=UNIX-TIMESTAMP-START &until=UNIX-TIMESTAMP-STOP &period=total_over_range &access_token=PAGE-ACCESS-TOKEN"
成功后,应用会收到以下 JSON 响应,其中包含新独立对话的数量以及时间范围的结束时间:
{ "data": [ { "name": "page_messages_new_conversations_unique", "period": "total_over_range", "values": [ { "value": 27 "end_time": "1665175977" } ], } ] }
以下示例查找特定时间段内按主题和频次分组的定期通知口令的总数。
curl -i -X GET "https://graph.facebook.com/LATEST-API-VERSION/PAGE-ID/insights/ ?metric=recurring_notifications_tokens &since=UNIX-TIMESTAMP-START &until=UNIX-TIMESTAMP-STOP &period=total_over_range &breakdown=recurring_notifications_topic,recurring_notifications_frequency &access_token=PAGE-ACCESS-TOKEN"
成功后,应用会收到以下 JSON 响应,其中包含按主题分组的口令“newproducts”和“10percentsale”,以及各主题可使用的消息发送频次(对于“newproducts”,频次为“daily”、“weekly”和“monthly”;对于“10percentsale”,频次为“daily”和“weekly”):
{ "data": [ { "name": "recurring_notifications_tokens", "period": "total_over_range", "values": [ { "value": 3, "end_time": "1665175977", "recurring_notifications_topic": "newproducts", "recurring_notifications_frequency": "daily" }, { "value": 15, "end_time": "1665175977", "recurring_notifications_topic": "newproducts", "recurring_notifications_frequency": "weekly" }, { "value": 8, "end_time": "1665175977", "recurring_notifications_topic": "newproducts", "recurring_notifications_frequency": "monthly" }, { "value": 17, "end_time": "1665175977", "recurring_notifications_topic": "10percentsale", "recurring_notifications_frequency": "daily" }, { "value": 14, "end_time": "1665175977", "recurring_notifications_topic": "10percentsale", "recurring_notifications_frequency": "weekly" }, ] } ] }
参数 | 描述 | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 对响应进行分组所依据的维度。可以为以下一种或多种类型:
| ||||||||||||||||
| 相对日期范围,可取代 | ||||||||||||||||
| 必要。待返回的以逗号分隔的指标清单 | ||||||||||||||||
| 在 since、until 或 date_preset 范围内提供的汇总周期。 | ||||||||||||||||
| 待查看数据所在日期范围的开始日期。包括所设日期从凌晨零点开始的数据。值的格式为 | ||||||||||||||||
| 待查看数据所在日期范围的结束日期。不包括所设日期从凌晨零点开始的数据。值的格式为 |
使用消息功能成效分析 API 可获取以下指标:
metric 名称 | 描述 |
---|---|
| 在与公共主页的对话中,被屏蔽的对话数量。 |
| 客户通过轻触行动号召按钮与企业公共主页所发送营销消息进行互动的次数。
这项指标仍在逐步发展。 |
| 由之前从未与您的企业开展过消息对话的用户在 Messenger 上发起的消息对话数量。 |
| 您在消息对话中或用于管理消息对话的第三方应用或网站中创建订单的次数。 这项指标仍在逐步发展。 |
| 您在通过消息对话或通过用于管理消息对话的第三方应用或网站创建的订单中所赚取的大概收入金额。最终收入可能因货币转换而有所出入。 这项指标仍在逐步发展。 |
| 已读营销消息的数量除以您公共主页所发送营销消息的数量。 在客户已关闭已读回执等情况下,部分消息阅读数据可能无法捕获。
这项指标仍在逐步发展。 |
| 在来自您公共主页的对话中,因包含垃圾信息或不当内容等原因被用户举报的对话数量。 |
| 企业公共主页向客户发送的消息的数量。
这项指标仍在逐步发展。 |
| 可作为企业发送消息目标的用户数量。 这项指标显示曾通过 Messenger 向您的企业发送过消息的用户(不包括已在 Messenger 上屏蔽或举报您商家的用户)数量。您向联系人发送消息的功能可能会受限,例如在特定时间范围内您可以发送的消息数量会受到限制。而且,这项指标仅包含从 2016 年 10 月之后建立联系的用户,因为只能获取此时间之后的数据。 |
| 创建了至少一个订单的消息联系人数量。 这项指标仍在逐步发展。 |
| 某个帐户订阅接收您企业营销信息的次数。如果一个帐户订阅了多个主题,则每个主题都将重新计入一次。 计算方式:这项指标计算帐户同意接收定期消息的次数减去帐户退订的次数。
这项指标仍在逐步发展。 |
详细了解处于逐步发展阶段的指标
在对成效分析 API 的调用中可能会返回以下信息。
属性 | 描述 |
---|---|
| 指标对象清单 |
name 字符串 | 指标名称 |
period 字符串 | 所报告数据所属的时间段 |
values 对象数组 | 指标的数据清单。 |
value 整数 | 指定日期范围内所请求指标的计数 |
end_time UNIX 时间戳 | 指标的结束时间,以 UTC 时间戳表示 |