メッセージインサイトAPI

このドキュメントでは、ビジネスが送受信したメッセージの指標を、プログラムを通して取得する方法について説明します。メッセージインサイトAPIはページインサイトAPIの拡張機能であり、Facebookページの[ページインサイト]タブに表示されるものと同じ情報を提供します。

開始する前に

所有しているFacebookページやANALYZEタスクを実行できるFacebookページの指標を確認するには、アプリに次のものが必要です。

• 指標を確認するFacebookページのページID

  • Instagramメッセージの場合は、InstagramプロアカウントにリンクされたFacebookページです
• ページアクセストークン
• 以下のアクセス許可

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• スタンダードアクセス

所有していないFacebookページや、ANALYZEタスクを実行することができないFacebookページの指標を確認するには、アプリに次のものが必要です。

• 指標を確認するFacebookページのページID

  • Instagramメッセージの場合は、InstagramプロアカウントにリンクされたFacebookページです
• ページでANALYZEタスクを実行できるユーザーがリクエストしたページアクセストークン
• Facebookログインによる以下のアクセス許可

  • pages_messaging
  • pages_read_engagement
  • pages_show_list
  • read_insights
• アドバンスアクセス

制限

• 新しいスレッドがカウントされるには、ビジネスに返信するなどのアクションを利用者が実行している必要があります。利用者がアクションを行うまで、スレッドはその利用者に対してのみ表示され、カウントされません。

インサイト指標を読み取る

1つ以上の指標の情報を読み取るには、確認する指標のコンマ区切りのリストに設定したmetricパラメーターを使用し、GETリクエストを/PAGE-ID/insightsエンドポイントに送信します。

リクエストの例

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」では「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への呼び出しでは、次の情報が返される可能性があります。

参考情報

• ページインサイトの詳細
• インサイトオブジェクトリファレンスの詳細