Webex CallingのCDRを取得して自由に処理してみる

turatake · ‎2023-03-23

電話システムの管理者や部門ユーザは通話料金を計算したり、ユーザの利用状況（投資したコストに対して利用されているのかなど）を把握したり、不正な通話を検出するためなど多様な目的のために全ての通話の通話履歴を収集して分析することがあります。

オンプレミスのCDRは呼制御サーバからFTPなどで定期的に出力されるCSV形式のデータをバッチで処理するようなワークフローで処理されることが一般的です。

SaaS型のクラウドサービスであるWebex Callingにおいても同様にCDR (呼詳細レコード) をControl HubまたはAPIで取得することが可能です。Webex CallingにつきましてはControl Hub上でさまざまなグラフィカルな分析レポートを閲覧することが可能であり、それで十分だというお客様も多いとは思います。

一方では、より詳細に分析して顧客サービスに活用したいというようなユースケースに対応するためにプログラムコードやBIツールなどで処理したいというニーズも多くあります。たとえば、放棄呼（着信したけれども誰も応答せずに切断されたコール）の発信元番号を集計したり、放棄呼の件数が多い時間帯や曜日などを集計して電話対応の優先度を上げるような場合などです。

Webex CallingのCDRおよび通話料金表からユーザ毎の通話料金を集計するサンプルがGitHub上に公開されています。

Webex CallingのAPIは容易にアクセスすることができます。（APIのための追加コストなどは不要です。Webexのライセンスのみで自由にご利用可能です。）

今回はWebex APIを通じてCDRをオンデマンドで取得し、その内容を処理する方法について例示してご説明いたします。CDRを取得するためのAPIの詳細はこちらのリンク先をご覧ください。

CDRのAPIは以下のような形式でデータを返します。

{
  "items": [
    {
      "Answer time": "2020-05-14T11:01:17.551Z",
      "Answered": "true",
      "Authorization code": "107",
      "Call ID": "SSE1101163211405201218829100@10.177.4.29",
      "Call type": "SIP_ENTERPRISE",
      "Called line ID": "CALLEDCLIDGOESHERE",
      "Called "Called number": "2002",
      "Calling line ID": "YOURCLIDGOESHERE",
      "Calling number": "2001",
      "Client type": "SIP_TOLLFREE",
      "Client version": "1.0.2.3",
      "Correlation ID": "8e8e1dc7-4f25-4595-b9c7-26237f824535",
      "Department ID": "4370c763-81ec-403b-aba3-626a7b1cf264",
      "Device MAC": "6C710D8ABC10",
      "Dialed digits": "1246",
      "Direction": "ORIGINATING",
      "Duration": 36,
      "Inbound trunk": "InTrunk",
      "International country": "US",
      "Location": "Richardson",
      "Model": "8851-3PCC",
      "Org UUID": "408806bc-a013-4a4b-9a24-85e374912102",
      "Original reason": "UserBusy",
      "OS type": "na",
      "Outbound trunk": "OutTrunk",
      "Redirect reason": "Unavailable",
      "Redirecting number": "+13343822691",
      "Related reason": "CallQueue",
      "Releasing party": "Remote",
      "Report ID": "0a0c2eb7-f1f6-3326-86f9-565d2e11553d",
      "Report time": "2020-05-14T11:01:52.723Z",
      "Route group": "RouteGrpAA",
      "Site main number": "+14692281000",
      "Site timezone": "-300",
      "Site UUID": "474d4f70-4ef5-4d52-9e1d-b207086629e0",
      "Start time": "2020-05-14T11:01:16.545Z",
      "Sub client type": "MOBILE_NETWORK",
      "Transfer related call ID": "2340586843:0A",
      "User": "John Andersen",
      "User type": "User",
      "User UUID": "47f0d0c2-f05a-44cc-870d-7a3daf859c6c"
      }
}

今回はwxcadmというWebex Calling管理用のPythonライブラリを利用してコードを書いています。

from dotenv import load_dotenv
import os
import pandas as pd
import wxcadm

load_dotenv()
access_token = os.getenv("WEBEX_ACCESS_TOKEN")
cdr_hours = os.getenv("CDR_HOURS", 25)
if not access_token:
    print("No WEBEX_ACCESS_TOKEN found. Cannot continue.")
    exit(1)

webex = wxcadm.Webex(access_token, get_people=False, get_locations=False)
try:
    cdrs = webex.org.calls.cdr(hours=int(cdr_hours))
except wxcadm.APIError:
    print("No CDRs returned")
    exit()

record_list = []
for cdr in cdrs:
    # 収集が必要なフィールドについてデータを採取します
    record = {
        'call_id': cdr['Call ID'],
        'user_uuid': cdr['User UUID'],
        'user_type': cdr['User type'],
        'location_uuid': cdr['Site UUID'],
        'location_name': cdr['Location'],
        'start_time': cdr['Start time'],
        'duration': cdr['Duration'],
        'answered': cdr['Answered'],
        'direction': cdr['Direction'],
        'call_type': cdr['Call type'],
        'intl_country': cdr['International country'],
        'location_timezone': cdr['Site timezone'],
        'calling_num': cdr['Calling number'],
        'dialed_digits': cdr['Dialed digits'],
        'called_num': cdr['Called number']
    }
    # レコードのリストに追加
    record_list.append(record)

# レコードのリストをPandasのDataFrameに変換
df = pd.DataFrame(record_list)

# ロケーションでグルーピングしたレコード数の件数
call_counts_by_location = df.groupby(by=['location_name']).size().reset_index(name='count')
print(f"ロケーション別のレコード数:\n{call_counts_by_location}\n")

# ユーザタイプでグルーピングしたレコード数の件数
call_counts_by_usertype = df.groupby(by=['user_type']).size().reset_index(name='count')
print(f"ユーザタイプ別のレコード数:\n{call_counts_by_usertype}\n")

実行結果は次のようになります

ロケーション別のレコード数:
  location_name  count
0         Tokyo     10

ユーザタイプ別のレコード数:
   user_type  count
0  HuntGroup      5
1       User      5

ライブラリを利用しているとはいえ、CDRのデータをとても簡単に取得できることはお分かりいただけたのではないでしょうか。今回はPandasのデータフレームに格納していますので、高度な集計処理を簡単に実装できるかと思います。

なお、管理者はAPIアクセスするユーザに対してCDRのへのAPIアクセスを行う役割を割り当てる必要があります

日本語表示の設定は以下のとおりです