消息功能成效分析 API

这份文档说明了如何以编程方式获取您企业所发送和接收消息的指标。消息功能成效分析 API 是公共主页成效分析 API 的扩展,可用于获取 Facebook 公共主页的“公共主页成效分析”选项卡中显示的信息。

准备工作

本指南假设您已经查看 Messenger 开放平台概览,并且已经实现发送和接收消息和通知所需的组件。

要查看您所拥有的或能够在其上执行 ANALYZE 任务的 Facebook 公共主页的指标,您的应用需要:

  • 您想查看的指标所属 Facebook 公共主页的公共主页编号
    • 对于 Instagram 消息功能,此公共主页为与 Instagram 专业帐户绑定的 Facebook 公共主页
  • 公共主页访问口令
  • 以下权限:
    • pages_messaging
    • pages_read_engagement
    • pages_show_list
    • read_insights
  • 标准访问级别

要查看非您所拥有的或无法在其上执行 ANALYZE 任务的 Facebook 公共主页的指标,您的应用需要:

  • 您想查看的指标所属 Facebook 公共主页的公共主页编号
    • 对于 Instagram 消息功能,此公共主页为与 Instagram 专业帐户绑定的 Facebook 公共主页
  • 公共主页访问口令,由可以在公共主页上执行 ANALYZE 任务的用户请求
  • 通过 Facebook 登录获取以下权限:
    • 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)以及定义时间范围的两个参数 sinceuntil

为方便阅读,示例格式已经过调整。
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"
        },
      ]
    }
  ]
}

成效分析参数

参数 描述

breakdown

对响应进行分组所依据的维度。可以为以下一种或多种类型:

名称描述

campaign_id

按广告系列编号查看数据。示例:“abc123”、“Summer messaging campaign”和“Spring sale 2”

engagement_source

按与定期通知互动的类型查看数据。示例:主要和次要行动号召 (CTA) 编号(所点击的行动号召)

message_type

按企业所发送消息的类型查看数据。示例:营销消息

messaging_channel

按向用户发送消息所使用的渠道查看数据。示例:Messenger 和 Instagram

recurring_notifications_entry_point

按定期通知的接入点查看数据。示例:对话中、聊天插件、CTM 广告、复选框插件、m.me 或 ig.me 链接和 Facebook 公共主页

recurring_notifications_frequency

按定期通知订阅所允许的频次查看数据。示例:每日、每周和每月

recurring_notifications_topic

按定期通知的主题查看数据。示例:推广消息、商品发布和交易

date_preset

相对日期范围,可取代 sinceuntil。可以是 last_weeklast_monthlast_quarter 等。阅读公共主页成效分析指南,了解更多值。

metric

必要。待返回的以逗号分隔的指标清单

period

在 since、until 或 date_preset 范围内提供的汇总周期。total_over_range 值提供了给定日期范围内指标的单个值。可以是 dayweekmonthdays_28total_over_range

since

待查看数据所在日期范围的开始日期。包括所设日期从凌晨零点开始的数据。值的格式为 YYYY-MM-DD。若值为 2022-01-31,将提供从 2022 年 1 月 31 日凌晨零点开始的数据。

until

待查看数据所在日期范围的结束日期。不包括所设日期从凌晨零点开始的数据。值的格式为 YYYY-MM-DD。若值为 2022-02-01,将提供到 2022 年 1 月 31 日晚上 11:59 为止的数据。

可用指标

使用消息功能成效分析 API 可获取以下指标:

metric 名称描述

page_messages_blocked_conversations_unique

在与公共主页的对话中,被屏蔽的对话数量。

page_messages_engagement

客户通过轻触行动号召按钮与企业公共主页所发送营销消息进行互动的次数。

breakdown 值可以是:

  • campaign_id
  • engagement_source
  • message_type
  • messaging_channel
  • recurring_notifications_topic

这项指标仍在逐步发展。

page_messages_new_conversations_unique

由之前从未与您的企业开展过消息对话的用户在 Messenger 上发起的消息对话数量。

page_messages_order_count

您在消息对话中或用于管理消息对话的第三方应用或网站中创建订单的次数。


这项指标仍在逐步发展。

page_messages_paid_order_earnings

您在通过消息对话或通过用于管理消息对话的第三方应用或网站创建的订单中所赚取的大概收入金额。最终收入可能因货币转换而有所出入。


这项指标仍在逐步发展。

page_messages_read_ratio

已读营销消息的数量除以您公共主页所发送营销消息的数量。

在客户已关闭已读回执等情况下,部分消息阅读数据可能无法捕获。

breakdown 值可以是:

  • campaign_id
  • message_type
  • messaging_channel
  • recurring_notifications_topic

这项指标仍在逐步发展。

page_messages_reported_conversations_unique

在来自您公共主页的对话中,因包含垃圾信息或不当内容等原因被用户举报的对话数量。

page_messages_sent

企业公共主页向客户发送的消息的数量。


breakdown 值可以是:

  • campaign_id
  • messsage_type
  • messaging_channel
  • recurring_notifications_topic

这项指标仍在逐步发展。

page_messages_total_messaging_connections

可作为企业发送消息目标的用户数量。


这项指标显示曾通过 Messenger 向您的企业发送过消息的用户(不包括已在 Messenger 上屏蔽或举报您商家的用户)数量。您向联系人发送消息的功能可能会受限,例如在特定时间范围内您可以发送的消息数量会受到限制。而且,这项指标仅包含从 2016 年 10 月之后建立联系的用户,因为只能获取此时间之后的数据。

page_messages_with_business_outcomes

创建了至少一个订单的消息联系人数量。


这项指标仍在逐步发展。

recurring_notifications_tokens

某个帐户订阅接收您企业营销信息的次数。如果一个帐户订阅了多个主题,则每个主题都将重新计入一次。


计算方式:这项指标计算帐户同意接收定期消息的次数减去帐户退订的次数。


breakdown 值可以是:

  • messaging_channel
  • recurring_notifications_frequency
  • recurring_notifications_topic

这项指标仍在逐步发展。

详细了解处于逐步发展阶段的指标

响应属性

在对成效分析 API 的调用中可能会返回以下信息。

属性 描述

data

对象数组

指标对象清单

name
字符串

指标名称

period
字符串

所报告数据所属的时间段

values
对象数组

指标的数据清单。

value
整数

指定日期范围内所请求指标的计数

end_time
UNIX 时间戳

指标的结束时间,以 UTC 时间戳表示