消息功能成效分析 API

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

准备工作

要查看您所拥有的或能够在其上执行 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）以及定义时间范围的两个参数 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"
        },
      ]
    }
  ]
}

成效分析参数

可用指标

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

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

响应属性

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

另请参阅

• 详细了解公共主页成效分析
• 详细了解成效分析对象参考文档