分析

このドキュメントは、ビジネス電話番号から送信されたメッセージの数、WhatsApp Businessアカウント(WABA)のコンバージョンの数とそのコスト、特定のテンプレートが読まれた回数など、メッセージ、コンバージョン、テンプレートの分析を取得する方法について説明しています。

リクエスト時にWABAに関連付けられているビジネス電話番号とテンプレートの指標のみが応答に含まれます。

データの取得

WhatsApp Businessアカウントのエンドポイントを使用して分析を取得します。

クエリ構文

GET /<WHATSAPP_BUSINESS_ACCOUNT_ID>
  ?fields=<FIELDS>.<FILTERING_PARAMETER>

クエリ文字列パラメーター

メッセージ分析

analyticsフィールドは、特定のWABAに関連付けられている電話番号によって送受信されたメッセージの数とタイプを提供します。スレッドの指標については、スレッド分析をご覧ください。/{whatsapp-business-account-ID}?fields=analytics.{filtering-parameters}を呼び出す際に、以下のパラメーターを追加できます。

分析パラメーター

例

シナリオ: WABAに関連付けられているすべての電話番号で送受信されたメッセージの数を取得する必要があるとします。

ソリューションの提案: 呼び出すURLを作成し、フィルタリングパラメーターとしてstart、end、granularityを含めます。次に、そのURLに対してGETリクエストを発行します。

curl -i -X GET \ 
"https://graph.facebook.com/v19.0/{whatsapp-business-account-ID}
      ?fields=analytics
      .start(1543543200)
      .end(1544148000)
      .granularity(DAY)
      &access_token={access-token}"

成功すると、応答としてリクエストしたデータが含まれるanalyticsオブジェクトが返されます。

{
  "analytics": {
    "phone_numbers": [
      "16505550111",
      "16505550112",
      "16505550113"
    ],
    "country_codes": [
      "US",
      "BR"
    ],
    "granularity": "DAY",
    "data_points": [
      {
        "start": 1543543200,
        "end": 1543629600,
        "sent": 196093,
        "delivered": 179715
      },
      {
        "start": 1543629600,
        "end": 1543716000,
        "sent": 147649,
        "delivered": 139032
      },
      {
        "start": 1543716000,
        "end": 1543802400,
        "sent": 61988,
        "delivered": 58830
      },
      {
        "start": 1543802400,
        "end": 1543888800,
        "sent": 132465,
        "delivered": 124392
      }
      # more data points
    ]
  },
  "id": "102290129340398"
}

スレッド分析

conversation_analyticsフィールドは、特定のWABAのコストとスレッドの情報を提供します。/{whatsapp-business-account-ID}?fields=conversation_analytics.{filtering-parameters}を呼び出す際に、以下のパラメーターを追加できます。

スレッド分析パラメーター

例

WABAに関連付けられている、特定の期間のスレッドとコストの情報を取得できます。必要なら、結果に対してフィルターと内訳を適用できます。例については、下記のコードサンプルをご覧ください。

すべての内訳を使って月ごとのデータを取得する

シナリオ: あるWABAに関連付けられているすべての電話番号の、特定の月のスレッドとコストの情報をすべて取り出します。

ソリューションの提案: 呼び出すURLを作成し、以下のフィルタリングパラメーターを含めます。

• start: 期間の始め。この場合、指標を調べる対象月の始まり。
• end: 期間の終わり。この場合、指標を調べる対象月の終わり。
• granularity: 希望するデータポイント粒度。下記の例では、MONTHLYを使っているため、各データポイントは1か月分のデータを表すことになります。
• phone_numbers: 空配列を送信します。該当WABAに関連する全電話番号の情報が返されます。
• dimensions: 可能なすべての内訳("CONVERSATION_CATEGORY"、"CONVERSATION_TYPE"、"COUNTRY"、"PHONE")に設定します。

この場合、country_codes、metric_types、conversation_types、conversation_categoriesを指定する必要はありません。これらのフィールドのいずれも送信しない場合は、選択可能なすべてのオプションが返されます。URLを設定したら、GETリクエストを発行します。

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800).end(1688194800)
  .granularity(MONTHLY)
  .phone_numbers([])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY","PHONE"])
  &access_token={access-token}"

成功すると、応答としてリクエストしたデータが含まれるconversation_analyticsオブジェクトが返されます。以下の例では、WABAに含まれる電話番号は1つだけです。

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1558,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.58
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2636,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 26.36
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2238,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "SERVICE",
            "cost": 22.38
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1782,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_category": "UTILITY",
            "cost": 17.82
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1568,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "AUTHENTICATION",
            "cost": 15.68
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2716,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "MARKETING",
            "cost": 27.16
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 2180,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "SERVICE",
            "cost": 21.8
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1465,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_TIER",
            "conversation_category": "UTILITY",
            "cost": 14.65
          },
          {
            "start": 1685602800,
            "end": 1688194800,
            "conversation": 1433,
            "phone_number": "15550458206",
            "country": "US",
            "conversation_type": "FREE_ENTRY_POINT",
            "conversation_category": "SERVICE",
            "cost": 14.33
          }
        ]
      }
    ]
  },
  "id": "102290129340398",
}

すべての内訳および半時間の粒度を使って特定の電話番号のデータを取得する

シナリオ: あるWABAに関連付けられている特定の電話番号の、特定の期間におけるスレッドとコストの情報をすべて取り出します。結果には、利用できるすべての内訳を使うものとします。各データポイントで半時間分のデータを表すことが必要です。

ソリューションの提案: 呼び出すURLを作成し、以下のフィルタリングパラメーターを含めます。

• start: 期間の始め。
• end: 期間の終わり。
• granularity: 希望するデータポイント粒度。下記の例では、HALF_HOURを使っているため、各データポイントは半時間分のデータを表すことになります。
• phone_numbers: 必要な情報の対象となる電話番号。
• dimensions: 可能なすべての内訳(CONVERSATION_CATEGORY、CONVERSATION_TYPE、COUNTRY、PHONE)に設定します。

この場合、country_codes、metric_types、conversation_types、conversation_categoriesを指定する必要はありません。これらのフィールドのいずれも送信しない場合は、選択可能なすべてのオプションが返されます。URLを設定したら、GETリクエストを発行します。

curl -i -X GET \
"https://graph.facebook.com/v19.0/{whatsapp-business-account-id}
  ?fields=conversation_analytics
  .start(1685602800)
  .end(1685689200)
  .granularity(HALF_HOUR)
  .phone_numbers(["19195552584"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE","COUNTRY,PHONE"])
  &access_token=your-access-token"

成功すると、リクエストしたデータが含まれるconversation_analyticsオブジェクトが応答として返されます。

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "SERVICE",
            "cost": 0.0232
          },
          {
            "start": 1685602800,
            "end": 1685604600,
            "conversation": 4,
            "phone_number": "19195552584",
            "country": "US",
            "conversation_type": "REGULAR",
            "conversation_direction": "UNKNOWN",
            "conversation_category": "MARKETING",
            "cost": 0.0232
          },
         # ... more data points
        ]
      }
    ]
  },
  "id": "102290129340398"
}

スレッドタイプの内訳を使って月ごとのデータを取得する

シナリオ: あるWABAに関連付けられているすべての電話番号の、特定の期間におけるスレッドとコストの情報をすべて取り出します。結果では、内訳をスレッドタイプ別に示します。

ソリューションの提案: 呼び出すURLを作成し、以下のフィルタリングパラメーターを含めます。

• start: 期間の始め。
• end: 期間の終わり。
• granularity: 希望するデータポイント粒度。下記の例では、MONTHLYを使っているため、各データポイントは半月分のデータを表すことになります。
• phone_numbers: 空配列を送信します。該当WABAに関連する電話番号の情報がすべて返されます。
• dimensions: CONVERSATION_TYPEに設定します。

この場合、country_codes、metric_types、conversation_types、conversation_directions、conversation_categoriesを指定する必要はありません。これらのフィールドのいずれも送信しない場合は、選択可能なすべてのオプションが返されます。URLを設定したら、GETリクエストを発行します。

curl -i -X GET
"https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
      ?fields=conversation_analytics
      .start(1643702400).end(1646121600)
      .granularity(MONTHLY)
      .phone_numbers([])
      .dimensions([CONVERSATION_TYPE])
      &access_token={access-token}"

成功すると、リクエストしたデータが含まれるconversation_analyticsオブジェクトが応答として返されます。

{
  "data": [
    {
      "data_points": [
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation": 8500,
          "conversation_type": "REGULAR",
          "cost": 88.1010
        },
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 1000,
          "conversation_type": "FREE_TIER",
          "cost": 0.0000
        }
        {
          "start": 1643702400,
          "end": 1646121600,
          "conversation”: 250,
          "conversation_type": "FREE_ENTRY_POINT",
          "cost": 0.0000
        }
      ]
    }
  ]
}

スレッドカテゴリの内訳を示す半時間のデータを取得する

リクエスト:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY"])
  &access_token={access-token}"  

応答:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          },
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_category": "MARKETING",
            "cost": 0.0432
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

#### スレッドのタイプとカテゴリの内訳を示す半時間のデータを取得する

リクエスト:

curl -i -X GET \
 "https://graph.facebook.com/v19.0/{whatsapp-buiness-account-id}
  ?fields=conversation_analytics
  .start(1685527200)
  .end(1685613600)
  .granularity(HALF_HOUR)
  .conversation_categories(["MARKETING","AUTHENTICATION"])
  .dimensions(["CONVERSATION_CATEGORY","CONVERSATION_TYPE"])
  &access_token={access-token}"  

応答:

{
  "conversation_analytics": {
    "data": [
      {
        "data_points": [
          {
            "start": 1685527200,
            "end": 1685529000,
            "conversation": 3,
            "conversation_type": "REGULAR",
            "conversation_category": "MARKETING",
            "cost": 0.0432
          },
          {
            "start": 1685529000,
            "end": 1685530800,
            "conversation": 2,
            "conversation_type": "REGULAR",
            "conversation_category": "AUTHENTICATION",
            "cost": 0.0128
          }
        ]
      }
    ]
  },
  "id": "102290129340398"
}

テンプレート分析

テンプレート分析は、テンプレートの送信、配信、読み取りの回数と、テンプレートの[URL]ボタンまたは[クイック返信]ボタンがクリックされた回数を報告します。

データはUTCタイムゾーンの日次単位で返され、最大過去90日分遡ることができます。テンプレート分析は、[WhatsAppマネージャ] > [メッセージテンプレート] > [テンプレートの詳細] > [インサイト]パネルにもあります。

制限

• テンプレート分析がオンプレミスAPIで利用できるのは、アカウントがクラウドAPIのテンプレート分析をオプトインしていない場合のみです。
• オンプレミスAPIのテンプレート分析には、集計および匿名化に関するガイドラインが適用されます。このガイドラインでは、カウントがユーザーに表示されるまでには少なくとも1000件のイベントが必要とされます。
• ボタンのクリック分析は、MARKETINGまたはUTILITYのカテゴリに分類されたテンプレートでのみ利用可能です。
• 欧州連合(EU)、英国、日本のMetaビジネスアカウントが所有しているまたは共有を受けているWABA、またはこれらの国や地域の国番号のビジネス電話番号を持つWABAは、サポートされていません。

不具合の報告

テンプレート分析の不具合を報告するには、次の項目を選択してダイレクトサポートチケットを送信してください。

• 質問トピック: WABiz: クラウドAPI
• リクエストタイプ: 不具合または実装の問題

テンプレート分析の確認

テンプレート分析を取得する前に、お持ちのWhatsApp Businessアカウントでテンプレート分析を確認する必要があります。WhatsAppマネージャまたはAPIを使用してテンプレート分析を確認することができます。APIを使って実行するには、次のリクエストを送信してください。

POST /<WHATSAPP_BUSINESS_ACCOUNT_ID>?is_enabled_for_insights=true

確認すると、WhatsApp Businessアカウントのテンプレート分析のキャプチャが開始されます。一度確認したテンプレート分析を無効にすることはできません。

成功すると、APIはWhatsApp BusinessアカウントIDで応答します。以下はその例です。

{                          
  "id": 102290129340398
}

テンプレート分析パラメーター

例

すべてのテンプレート分析を取得する

シナリオ: WhatsApp Businessアカウントに関連付けられている1つのメッセージテンプレートの、特定の2日間のテンプレート分析をすべて取得します。

リクエストの例:

curl -g 'https://graph.facebook.com/v19.0/109259195336416/template_analytics?start=1689379200&end=1689552000&granularity=DAILY&metric_types=[%27SENT%27%2C%27DELIVERED%27%2C%27READ%27%2C%27CLICKED%27]&template_ids=[1924084211297547%2C954638012257287]' \
-H 'Authorization: Bearer EABN8...'

応答の例:

{
  "data": [
    {
      "granularity": "DAILY",
      "data_points": [
        {
          "template_id": "1924084211297547",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 3
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 5
            }
          ]
        },
        {
          "template_id": "1924084211297547",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "quick_reply_button",
              "button_content": "Tell me more",
              "count": 73
            },
            {
              "type": "quick_reply_button",
              "button_content": "Get coupon",
              "count": 35
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689379200,
          "end": 1689465600,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 13
            }
          ]
        },
        {
          "template_id": "954638012257287",
          "start": 1689465600,
          "end": 1689552000,
          "sent": 0,
          "delivered": 0,
          "read": 0,
          "clicked": [
            {
              "type": "url_button",
              "button_content": "Visit Website",
              "count": 12
            }
          ]
        }
      ]
    }
  ],
  "paging": {
    "cursors": {
      "before": "MAZDZD",
      "after": "MjQZD"
    }
  }
}

ボタンのクリック分析の無効化

個々のテンプレートのボタンクリック数のトラッキングは、そのcta_url_link_tracking_opted_outフィールドをtrueに設定すれば無効化できます。無効化されると、APIはクリックされたプロパティをテンプレート分析で返さなくなり、テンプレートのインサイトを表示する際にボタンのエンゲージメント/クリック数がWhatsAppマネージャに表示されなくなります。

リクエストの構文

POST /<TEMPLATE_ID>
  ?cta_url_link_tracking_opted_out=<OPT_OUT>
  &category=<TEMPLATE_CATEGORY>

リクエストのパラメーター

リクエストの例

curl -X POST 'https://graph.facebook.com/v19.0/245435364965041?cta_url_link_tracking_opted_out=true&category=marketing' \
-H 'Authorization: Bearer EAAJB...'

応答の例

成功すると、APIは以下のように応答します。

{
    "success": true
}

リファレンス

各フィールドで指定可能なすべての値のリストについては、WhatsApp Businessアカウントの分析フィールドのグラフAPIリファレンスをご覧ください。