How to Visualize WhatsApp Account Metrics in Your App
WhatsAppのビジネス管理APIを使って、WhatsApp Businessアカウント(WABA)に関する指標や分析にアクセスできます。アカウントに関して得られる情報のタイプは次の2とおりです。
- メッセージの分析: 特定の期間内に特定のWABAに関連付けられた電話番号によって送信および配信されたメッセージの件数。
- スレッドの分析: 特定の期間内に送信されたメッセージのスレッドとコストに関する情報。
APIエンドポイントをクエリする際には、URLのパラメーターとして analytics または conversation_analytics を追加することにより、メッセージまたはスレッドのどちらの分析を取得するかを指定する必要があります。
例えば、アカウントに関するメッセージの分析を取得する場合のリクエストのサンプルは、次のようになります。
https://graph.facebook.com/v14.0/{whatsapp-business-account-ID}
?fields=analytics
.{filtering-parameters}
&{access-token}このサンプルでは、固有のWABA IDを持つWABAにリンクされた電話番号のメッセージの分析を取得することが指定されています。WABA IDとアクセストークンの取得方法について詳しくは、以降の要件のセクションで説明します。
また、リクエストを行う際には、フィルタリングパラメーターを適用して結果を絞り込むことができます。ビジネス管理APIのエンドポイントでは、合計で6つのフィルタリングパラメーターがサポートされています。以下は必須です。
start: 開始日を指定する場合、指定された日付より前に送信されたメッセージは応答に含まれません。end: 終了日を指定する場合、指定された日付より後に送信されたメッセージは応答に含まれません。granularity: どの程度詳細な分析を得たいか。指定可能な値はHALF_HOUR、DAY、MONTHなどです。
conversation_analyticsの場合、9個のフィルタリングパラメーターがありますが、そのうちの start、 end、 granularity は必須です。
要件
このチュートリアルには次の要件があります。
Pythonとpipをローカルの開発用マシンにインストールする。*
Meta for Developersの開発者アカウントを登録し、ビジネスタイプのアプリを作成して、そのアプリにWhatsApp Businessアカウントを追加する。
[アプリに製品を追加する]ページで、[WhatsApp]オプションの[設定]ボタンをクリックして設定する。
WhatsAppビジネスタイプのアプリの作成が完了すると、WABA IDと一時的なアクセストークンが提供されます。このチュートリアルでは、今後これら2つのキーが必要になりますので、記録しておいてください。
個人的なWhatsApp番号を送信者として追加することも、WhatsApp提供のテスト用電話番号を使うこともできます。
データを視覚化するPythonアプリの作成
Python開発環境をセットアップし、必要なパッケージをインストールします。
フォルダを作成して名前を付けたら、コマンドラインツールを使ってそのフォルダにナビゲートします。このブログでは、HTTPリクエストを行うリクエストライブラリと、静的な視覚化、アニメーション付きの視覚化、インタラクティブな視覚化を作成する際によく使われるMatplotlibライブラリを使います。次のコマンドを実行してこれらをインストールします。
pip install requests matplotlib
これで、Pythonリクエストを使ってAPIでWhatsAppからの分析データをクエリできるようになり、APIから受信したデータポイントを利用してグラフを作図することで、Matplotlibを使って指標を視覚化できるようになります。
1日あたりに送信されるメッセージ件数の視覚化
まず、分析データをリクエストします。そのためには、アプリフォルダ内に sent.py という名前のファイルを作成し、このタスクに必要な依存関係をインポートします。
import datetime import requests import matplotlib.pyplot as plt
次に、APIの GET リクエストを行って、WABA IDとアクセストークンを使って分析を取得します。これらの値は、Meta for Developerの開発者アカウントのダッシュボードで確認できます。 GET リクエストのコードは次のようになります。
key = 'put-your-access-token-here'
waba_id = 'put-your-waba-id-here'
res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=analytics.start(1662174000).end(1662548446).granularity(DAY)&access_token={key}')
dict = res.json()
print(dict)上記のリクエストでは、開始日をAPIの要件であるUNIXスタイルで表しています。こちらの無料のコンバーターを使って、人間が読める形式のタイムスタンプとUNIXタイムスタンプとの間で変換できます。このコードは、最後の行で応答をJSON形式に変換して、プリントします。
次のコマンドを使ってコードを実行します。
python app.py
WABAにリンクされた電話番号が、指定された時間枠内でメッセージの送信に使われると、次のようなディクショナリオブジェクトを応答として受け取ります。
{
"analytics": {
"phone_numbers": [
"16505550111",
"16505550112",
"16505550113"
],
"country_codes": [
"US",
],
"granularity": "DAY",
"data_points": [
{
"start": 1662174000,
"end": 1662260400,
"sent": 199251,
"delivered": 183001
},
{
"start": 1662260400,
"end": 1662346800,
"sent": 162489,
"delivered": 141234
},
{
"start": 1662346800,
"end": 1662433200,
"sent": 67902,
"delivered": 53902
},
{
"start": 1662433200,
"end": 1662519600,
"sent": 129521,
"delivered": 117832
}
]
},
"id": "952305634918047"
}
この場合、 data_points リストには、4つのディクショナリが含まれます。それぞれのディクショナリには、リンクされたWhatsApp電話番号が指定された日付範囲の間に送信および配信したメッセージの件数が入ります。
データが完成したので、必要な情報を取得します。1日あたりに送信されるメッセージの件数を視覚化するため、各ディクショナリから start 値と sent 値を取得する必要があります。
そのためには、Pythonの for...in ループを使ってデータポイントをループします。データオブジェクトごとに、開始時間をUNIXスタイルから人間が読めるバージョンに変換します。次に、月の日を表す数字のみを取得して、それを日のリストに追加します。送信されたメッセージの件数を no_of_msgs_sentという名前の別のリストに保存します。
days = []
no_of_msgs_sent = []
data_points = dict.get("analytics").get("data_points")
for point in data_points:
# Get date in human readable format
x = datetime.datetime.fromtimestamp(point.get('start'))
# Get just the day in string format
y = x.strftime("%d")
days.append(y)
# Add the number of sent messages to the list
no_of_msgs_sent.append(point.get('sent'))
print(days)
print(no_of_msgs_sent)
If you run the code, you get two lists:
['03', '04', '05', '06'] // days
[196093, 147649, 61988, 132465] // number of messages
Now that you have what you need, it's time to visualize it. Add the following code to app.py:
plt.plot(days, no_of_msgs_sent)
plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Number of messages sent')
plt.show()
ここでは、X軸に日を表す数字を、Y軸に送信メッセージの件数を示した基本のグラフを作図します。
ファイルを保存し、コードを実行します。Linux環境を使っており、次のようなエラーを受け取る場合:
UserWarning: Matplotlib is currently using agg, which is a non-GUI backend, so cannot show the figure.
tkinterがインストール済みであることを確認します。インストールされていなければ、次のコマンドを実行してインストールしてください。
sudo apt-get install python3-tk
コードを実行すると、次のようなグラフが得られます。
次に、配信されたメッセージの件数を視覚化するグラフを作成します。
特定のWhatsApp番号の情報の視覚化
前のセクションでは、リクエストに電話番号を含めませんでした。その結果、APIから、指定された開始日と終了日の範囲内の、WABAにリンクされたすべての電話番号の情報が返されました。
すべての電話番号ではなく、1つまたは複数の電話番号の分析データを取得する場合、リクエストを行う際に、該当する電話番号を配列に指定して .phone_numbers メソッドに渡す必要があります。
res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=analytics.start(1662174000).end(1662548446).phone_numbers([16505550111, // others]).granularity(DAY)&access_token={key}')それ以外の sent.py のコードは同じです。これを実行すると、指定された電話番号の分析のみを取得します。
1日あたりに配信されるメッセージの件数の視覚化
前の2つのセクションでは、グラフを作図して、リンクされた電話番号によってWhatsAppから1日あたりに送信されるメッセージの件数を視覚化しました。このセクションでは、1日あたりに配信されるメッセージの件数を視覚化しましょう。
新しいファイルを作成し、 delivered.pyと名前を付けます。次に、コードを sent.py から delivered.pyにコピーします。
続いて、 delivered.py内のコードにいくつかの変更を加えます。まず、上部の no_of_msgs_sent 変数の名前を、保存しているデータの種類を反映する no_of_msgs_del に変更します。
さらに、 for...in ループで、 point.get メソッドの値を sent から deliveredに変更します。以下は、変更を加えた状態のコードの断片です。
# Variables go here
for point in data_points:
# Code for getting human readable date goes here
# Now add the number of delivered messages to the list
no_of_msgs_del.append(point.get('delivered'))
print(day)
print(no_of_msgs_del)
Finally, specify no_of_msgs_del in the plt.plot method and update the label shown on the y-axis:
plt.plot(days, no_of_msgs_del)
plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Number of messages delivered')
plt.show()端末でコードを( python delivered.pyを指定して)実行すると、次のようなグラフが表示されます。
メッセージの2とおりの分析データを表すことができました。次は、メッセージのコストを conversation_analyticsを使って表します。
1日あたりに送信されるメッセージのコストの視覚化
このセクションでも、新しいファイルを作成して、 cost.pyと名前を付けます。コードを sent.py から cost.pyにコピーします。ここで、いくつかの変更を加えます。
まず、リクエストコードを変更します。スレッド情報を取得しようとしているので、 fields パラメーターを conversation_analytics に設定し、 granularity を dailyに設定します。
res = requests.get(f'https://graph.facebook.com/v14.0/{waba_id}?fields=conversation_analytics.start(1662174000).end(1662548446).granularity(DAILY).phone_numbers([])&access_token={key}')別の種類の情報を取得するため、 conversation_anaytics フィールドでは別のフィルタリングパラメーターもいくつかサポートされています。詳しくは、ドキュメント全体をご覧ください。
上記のリクエストを行ったら、次のような応答オブジェクトを受け取るはずです。
{
"conversation_analytics": {
'data': {
"data_points": [
{
"start": 1662174000,
"end": 1662260400,
"conversation": 5250,
"cost": 45.0532
},
{
"start": 1662260400,
"end": 1662346800,
"conversation": 2250,
"cost": 25.0290
},
{
"start": 1662346800,
"end": 1662433200,
"conversation": 800,
"cost": 0.0000
},
{
"start": 1662433200,
"end": 1662519600,
"conversation": 3150,
"cost": 33.2015
}
]
}
},
}上記で確認したように、 data_points はデータディクショナリの内部にあります。ディクショナリ内の各データポイントには、スレッドの量とコストがあります。
次に、 cost.pyで、上部の変数を no_of_msgs_del から cost_of_convoに変更します。 for...in ループで、 point.get メソッドの値を delivered から costに変更します。以下は、変更を加えた状態のコードの断片です。
days = []
cost_of_convo = []
data_points = dict.get('conversation_analytics').get("data").get("data_points")
for point in data_points:
x = datetime.datetime.fromtimestamp(point.get('start'))
y = x.strftime("%d")
days.append(y)
# Add the cost of messages in each data point
cost_of_convo.append(point.get('cost'))
Now, to plot a graph visualizing it:
plt.plot(days, cost_of_convo)
plt.title('Our Graph')
plt.xlabel('Days')
plt.ylabel('Cost of messages sent')
plt.show()端末でコードを( python cost.pyを指定して)実行すると、次のようなグラフが表示されます。
これで完了です。
さらに掘り下げて分析する場合は、同じ手法に従って、WhatsAppビジネス管理APIが提供する他の指標も視覚化してみましょう。
まとめ
このチュートリアルでは、matplotlibデータ視覚化ライブラリを使って、1日あたりのメッセージ送信件数、1日あたりのメッセージ配信件数、および各メッセージスレッドのコストを示すデータを視覚化しました。
フィルタリングパラメーターを始め、機能の充実したWhatsAppビジネス管理APIを使うと、各リクエストに必要な指標を指定できます。詳しくは、APIのドキュメント全体をご覧ください。
開発者は、WhatsAppビジネス管理APIを使って、ユーザーのWhatsAppアカウントから関連する情報や指標を取得できます。例えば、ユーザーがダッシュボードで、特定の日に送信したWhatsAppメッセージの件数を確認できるようにすることができます。
可能性は無限です。
*Metaは、サードパーティのアプリに関して一切の責任を負いません。
