訊息洞察報告 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 呼叫中加入設為 total_over_range 的 period 參數，並使用 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 時，系統可能會傳回以下資訊。

另請參閱

• 進一步了解專頁洞察報告
• 進一步了解洞察報告物件參考資料