Calls History APIを利用し、コールログを自動収集する

本チュートリアルでは、NTTCPaaS の Calls History API と Google Apps Script を活用し、通話履歴(コールログ)を自動でGoogleスプレッドシートへ書き出す仕組みを構築します。

1. 目的

「毎日・毎週、NTTCPaaSの管理画面ポータルから通話レポート(CSV/Excelなど)をダウンロードし、手作業でスプレッドシートに転記している……」といった運用作業に負担を感じていませんか?

手作業による転記は時間や工数がかかるだけでなく、転記ミスやデータの欠損が発生するリスクをはらんでいます。また、集計タイミングが担当者の作業スピードに依存してしまうため、リアルタイムに近いデータ分析や業務改善のアクションへ迅速につなげにくいという課題もあります。

本記事では、NTTCPaaSの Calls History API と Google Apps Script(GAS) を組み合わせ、通話履歴(コールログ)をGoogleスプレッドシートへ自動的に収集・蓄積する連携手順を解説します。特別なサーバー構築を行うことなく、無料かつ簡易に自動連携フローを確立できます。

2. 概要

Calls History API と、Googleスプレッドシート標準の「Google Apps Script(GAS)」を組み合わせれば、定期的にAPIを呼び出すだけで完備されます。欠損リスクを最小限に抑えつつ、堅牢で安定した自動集計ラインをサーバーレスかつノーコード感覚で構築できるため、今回の運用自動化には最も最適な手法です。 そのほか、こちらではご紹介しませんが、Pythonで実施しExcelで集計するといった、APIを選択する方法もあり、お客様によって使える商材によって、変えられます。call history APIを呼び出す場所があればいろいろなところに応用できます。 https://docs.nttcpaas.com/api/voice.html#tag/calls-management/GET/calls/1/calls/history

3. 実践シナリオ

【事前準備】(ステップ0)

開発・設定に入る前に、以下の準備を行います。

1. NTTCPaaS 管理画面での準備

  • APIキー(API Key)の確認・発行

    NTTCPaaSポータル(管理画面)にログインし、画面左のメニューから、
    デベロッパーツール > APIキーへ遷移し、認証用の API Key を取得・コピーしておきます。

  • ベースURLの確認

    ご利用環境のベースURL(例: https://m9mpkw.ibapi.nttcpaas.com など)を確認しておきます。
    参考ドキュメント:https://docs.nttcpaas.com/startup/base_url_and_api_key.html

2.Googleスプレッドシートの準備

  1. Google Drive から新規の「Google スプレッドシート」を作成します。
  2. シート名を report に変更します。
  3. 1行目(ヘッダー)に、わかりやすいように以下の項目名を入力しておきます。
    • A1: Call ID
    • B1: From (発信元)
    • C1: To (着信先)
    • D1: Direction (方向)
    • E1: State (ステータス)
    • F1: Start Time (開始日時)
    • G1: Duration (通話時間/秒)
    • H1: Error Code ID
    • I1: Error Description

【ステップ1】Google Apps Script(GAS)の作成

  1. 作成したGoogleスプレッドシートの上部メニューから [拡張機能] > [Apps Script] をクリックします。
  2. エディタが開いたら、デフォルトで入力されているコード(function myFunction() ...)を全て消去します。
  3. 以下のスクリプトをコピーしてエディタに貼り付けます。
function fetchCallHistory() {
  const SHEET_NAME = 'report'; // スプレッドシートのシート名
  const API_KEY = 'YOUR_API_KEY_HERE'; // ★ここに取得したNTTCPaaSのAPIキーを入力してください
  const BASE_URL = 'https://m9mpkw.ibapi.nttcpaas.com'; // ★ご利用環境のベースURLに合わせて変更してください
  
  // GETメソッドのパラメータ(pageやsize)はURLの末尾に付与します
  const page = 0;
  const size = 20;
  const URL = `${BASE_URL}/calls/1/calls/history?page=${page}&size=${size}`;
  
  // 1. APIリクエストの設定
  const options = {
    method: 'GET',
    contentType: 'application/json',
    headers: {
      'Authorization': 'App ' + API_KEY
    },
    muteHttpExceptions: true
  };
  
  try {
    // 2. APIを実行してデータを取得
    const response = UrlFetchApp.fetch(URL, options);
    const responseCode = response.getResponseCode();
    
    if (responseCode !== 200) {
      Logger.log('APIエラー: ステータスコード ' + responseCode);
      Logger.log(response.getContentText());
      return;
    }
    
    const json = JSON.parse(response.getContentText());
    const results = json.results;
    
    if (!results || results.length === 0) {
      Logger.log('新しいデータはありませんでした。');
      return;
    }
    
    // 3. スプレッドシートの準備
    const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName(SHEET_NAME);
    
    // 既存の通話IDを重複除去のために取得
    const lastRow = sheet.getLastRow();
    const existingIds = [];
    if (lastRow > 1) {
      const idValues = sheet.getRange(2, 1, lastRow - 1, 1).getValues();
      idValues.forEach(row => existingIds.push(row[0]));
    }
    
    // 4. データを配列に整形(重複していないものだけを抽出)
    const rowsToAppend = [];
    
    results.forEach(call => {
      const callId = call.callId;
      
      // 既に書き込み済みのcallIdはスキップする(重複登録防止)
      if (existingIds.includes(callId)) {
        return;
      }
      
      const from = call.from || 'unknown';
      const to = call.to || 'unknown';
      const direction = call.direction || '';
      const state = call.state || '';
      const startTime = call.startTime || '';
      const duration = call.duration !== undefined ? call.duration : 0;
      const errorCodeId = call.errorCode ? call.errorCode.id : '';
      const errorDescription = call.errorCode ? call.errorCode.description : '';
      
      rowsToAppend.push([
        callId,
        from,
        to,
        direction,
        state,
        startTime,
        duration,
        errorCodeId,
        errorDescription
      ]);
    });
    
    // 5. 新しいデータがあればシートの末尾に追加
    if (rowsToAppend.length > 0) {
      // 古い順・新しい順の並びを考慮し配列を反転して末尾追記
      rowsToAppend.reverse();
      sheet.getRange(sheet.getLastRow() + 1, 1, rowsToAppend.length, rowsToAppend[0].length).setValues(rowsToAppend);
      Logger.log(rowsToAppend.length + ' 件の新しい通話履歴を追加しました。');
    } else {
      Logger.log('新規追加する通話履歴はありませんでした。');
    }
    
  } catch (error) {
    Logger.log('スクリプト実行中にエラーが発生しました: ' + error.toString());
  }
}

【ステップ2】設定値の変更とコードの解説

コード内の以下の箇所をご自身の環境に合わせて書き換えてください。

  1. API_KEY の設定:const API_KEY = 'YOUR_API_KEY_HERE'; の部分をご自身のNTTCPaaS APIキーに置き換えます。
  2. BASE_URL の確認: ご自身のテナント用のベースURLに変更してください。

ポイント解説

  • 認証方式: NTTCPaaS APIのヘッダー認証には 'Authorization': 'App ' + API_KEY 形式を使用します。
  • 重複チェック機能: existingIds 配列を用いてシート内の既存 callId を読み込み、毎回実行された際に重複して同じコールログが追記されるのを防いでいます。

【ステップ3】手動テスト実行

  1. GASエディタ上部の関数選択ドロップダウンで fetchCallHistory が選択されていることを確認し、[実行] ボタンをクリックします。
  2. 初回実行時は「承認が必要です」というポップアップが表示されます画面の指示に従ってアクセス権限を許可してください。
  3. 実行完了後、下部の「実行ログ」に「〇件の新しい通話履歴を追加しました」と表示され、スプレッドシートに通話データが追記されていることを確認します。

【ステップ4】定期実行(トリガー)の設定

手動実行が確認できたら、毎日または数時間おきに自動でデータを取り込む設定を行います。

  1. GAS画面の左側メニューにある 「トリガー(時計アイコン)」 をクリックします。
  2. 右下の [トリガーを追加] ボタンをクリックします。
  3. 以下の通り設定します:
    • 実行する関数を選択: fetchCallHistory
    • イベントの源を選択: 時間駆動型
    • 時間型トリガーのタイプを選択: 日付ベースのタイマー(または 時間ベースのタイマー)
    • 時刻を選択: 午前8時〜9時(または 1時間おき など任意の時刻)
  4. [保存] をクリックします。

これで指定したスケジュールに従い、GASがNTTCPaaSから最新のコールログを判定・自動転記してくれます。

4. まとめと次のステップ

本チュートリアルでは、NTTCPaaS の Calls History API と Google Apps Script を活用し、通話履歴(コールログ)を自動でGoogleスプレッドシートへ書き出す仕組みを構築しました。
これにより、日々のポータルからのダウンロード・手動転記作業の手間(工数)を削減し、データ転記ミスの発生を防ぐことができます。

次の施策への展開(データ活用)

自動集計されたスプレッドシートのデータをベースに、以下のようなステップでさらなる業務改善やデータ活用へと繋げることができます。

  1. グラフによるダッシュボード化とメール配信
    • 月別の通話件数を可視化し、応対品質やコールセンターの稼働状況を把握する
    • それを、同じくGASで関係者あてにメールを配信するプログラムを構築し、定期監視できるようにする。
  2. SMSやメールの配信状況も他APIを使用し監視対象を拡大

手動連携から脱却し、蓄積されたデータを迅速な意思決定や改善施策へぜひご活用ください。

NTT CPaaSを、
60日間無料でお試しください

・SMS・Voice・メールを本番同様に無料で検証
・全API機能に即日アクセス / 有料プランと同一環境
・国内開発者向けに最適化された日本語ガイド

無料トライアル

目次
  1. 1. 目的
  2. 2. 概要
  3. 3. 実践シナリオ
    1. 【事前準備】(ステップ0)
      1. 1. NTTCPaaS 管理画面での準備
      2. 2.Googleスプレッドシートの準備
    2. 【ステップ1】Google Apps Script(GAS)の作成
    3. 【ステップ2】設定値の変更とコードの解説
    4. 【ステップ3】手動テスト実行
    5. 【ステップ4】定期実行(トリガー)の設定
  4. 4. まとめと次のステップ
    1. 次の施策への展開(データ活用)

2026.10.19