訊息洞察報告 API

本文件說明如何透過程式設計的方式取得商家已傳送或接收之訊息的衡量指標。訊息洞察報告 API 是粉絲專頁洞察報告 API 的擴充功能，可讓您取得自己 Facebook 粉絲專頁的「粉絲專頁洞察報告」頁籤中的相同資訊。

準備工作

若要檢視您擁有之 Facebook 粉絲專頁的衡量指標，或要在粉絲專頁上執行 ANALYZE 任務，您的應用程式需要以下項目：

• 所要查看之衡量指標的 Facebook 粉絲專頁的粉絲專頁編號

  • 對於 Instagram 傳訊功能，此為連結至 Instagram 專業帳號的 Facebook 粉絲專頁
• 粉絲專頁存取權杖
• 需要下列權限：

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• 一般存取權限

若要檢視非您擁有的 Facebook 粉絲專頁的衡量指標，或無法在粉絲專頁上執行 ANALYZE 任務，您的應用程式需要以下項目：

• 所要查看之衡量指標的 Facebook 粉絲專頁的粉絲專頁編號

  • 對於 Instagram 傳訊功能，此為連結至 Instagram 專業帳號的 Facebook 粉絲專頁
• 可在粉絲專頁上執行 ANALYZE 任務之用戶所要求的粉絲專頁存取權杖
• 透過 Facebook 登入獲得以下權限：

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• 進階存取權限

限制

• 用戶必須執行一項動作，例如傳送回覆給您的商家，才會將新對話納入計數。在用戶採取動作之前，只有用戶可以看到該對話，且不會納入計數。

讀取洞察報告衡量指標

若要讀取一或多個衡量指標的資訊，請向 /PAGE-ID/insights 端點傳送 GET 要求，並將 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」可用的訊息頻率為「每日」、「每週」和「每月」，「10percentsale」可用的訊息頻率為「每日」和「每週」：

{
  "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 時可能會傳回以下訊息。

另請參閱

• 深入瞭解粉絲專頁洞察報告
• 深入瞭解洞察報告物件參考資料