※本マニュアルは、BIZTELバージョン 3.10.X以降をご利用のユーザ様向けです。
BIZTELバージョン 3.9.Xまでをご利用の場合は、「5.レポート取得API（エージェントレポート）※3.9.Xまで」を参照ください。
| 目的 |
外部システムとBIZTELを連携することで、コールセンターに関する通話レポートの集計値を外部システムに連携することが可能です。 |
|---|---|
| 対象プラン |
|
| 用語 |
【WebAPI】 汎用的なWeb技術を利用し、インターネットを介して外部システムとの連携を容易にする仕組みです。 【BIZTEL API】 BIZTELが公開するAPIを示します。 |
| ポイント |
・本機能は、BIZTELバージョン 3.10.X 以降で利用可能です。 ・本機能をご利用いただく場合、「レポート取得API」のライセンス契約が必要です。 ・月間のAPIリクエスト数、APIレスポンスオブジェクト数の上限は、各100,000件となります。 ・管理画面上のエージェントレポート：着信の集計対象や詳細は「3.エージェントレポート：着信（3.10.X以降）」を参照ください。 |
・本マニュアルはHTML/PHP(PCRE正規表現等)/WebAPIの基礎的な技術知識がある、WEB系開発者様やCRMベンダー様を対象にしております。
目次
1.レポート取得APIの基本機能
レポート取得APIは、BIZTELと外部システムの連携により、外部システムからBIZTELの各種レポートの内容を取得可能とします。
取得可能なレポートは以下となります。
・コールセンターレポート：着信（8.レポート取得API（コールセンターレポート：着信）※3.10.X以降）を参照ください。
・コールセンターレポート：発信（9.レポート取得API（コールセンターレポート：発信）※3.10.X以降）を参照ください。
・エージェントレポート：着信（本マニュアルの範囲です）
・エージェントレポート：発信（11.レポート取得API（エージェントレポート：発信）※3.10.X以降）を参照ください。
・電話番号レポート：発信（12.レポート取得API（電話番号レポート：発信）※3.10.X以降）を参照ください。
※アウトバウンド機能（自動発信業務）のレポートは取得対象外となりますのでご注意ください。
2.通話・ステータスレポートの取得
2.1 API仕様
URI schemeは以下となります。
| Host | sXXXXXXXXXXXX.u.biztel.jp:8000 | BIZTELサーバアドレスとして指定されたFQDN |
|---|---|---|
| scheme | HTTPS | - |
2.2 リクエスト方式
通話・ステータスレポートのデータを取得際のリクエスト方式は以下となります。
| 認証方式 | HTTPメソッド | URI | 備考 |
|---|---|---|---|
| APIトークン認証方式 | GET | /public/api/v1/report/agent/call_status |
APIトークンによるアカウント認証が必要です。 |
2.3 リクエストパラメータ
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| from | 集計開始日時を指定します | 画面での該当項目：集計開始日時 画面での該当項目は必須項目です |
No | query | string |
当日0時 yyyy/mm/dd hh:mm |
| to | 集計終了日時を指定します | 画面での該当項目：集計終了日時 画面での該当項目は必須項目です |
No | query | string |
翌日0時 (当日の24時) yyyy/mm/dd hh:mm |
| category | 集計対象を選択します | 画面での該当項目：集計対象 0：コールセンター 1：業務ラベル |
No | query | integer |
0 ※0 ～ 1で入力ください。 |
| queue_ids | コールセンターを選択します | 画面での該当項目：コールセンター 集計対象プルダウンでコールセンターを選択時 |
Yes: 集計対象未入力または集計対象プルダウンでコールセンターを選択時 No: 集計対象プルダウンで業務ラベルを選択時 |
query | string | -- |
| business_ids | 業務ラベルを選択します | 画面での該当項目：業務ラベル 集計対象プルダウンで業務ラベルを選択時 |
Yes: 集計対象プルダウンで業務ラベルを選択時 No: 集計対象未入力または集計対象プルダウンでコールセンターを選択時 |
query | string | -- |
| account_ids | エージェントを選択します | 画面での該当項目：エージェント | Yes | query | string | -- |
| ringnoanswer_sec | 応答不能集計秒数を選択します | 画面での該当項目：応答不能集計秒数 | No | query | integer | 0 |
| account_status_ids | ステイタスを選択します | 画面での該当項目：表示設定のステイタス 1：後作業（CC紐づけなし） 2：休憩中 3：離席中 |
No | query | string | -- |
| occupancy_status_ids | 稼働率の算出方法種別を選択します | 画面での該当項目：詳細設定の稼働率の算出方法種別 1：後作業（CC紐づけなし） 時間を稼働時間に含める 2：休憩中 時間を稼働時間に含める 3：離席中 時間を稼働時間に含める |
No | query | string | -- |
| queue_specific_account_status_ids | 自動変更ステータスを含む | 画面での該当項目：1000：後作業（CC紐づけあり） 1：後作業（CC紐づけあり） |
No | query | string | -- |
| queue_specific_occupancy_status_ids | 自動変更ステータスを稼働率に含む | 画面での該当項目：1000：後作業（CC紐づけあり） 時間を稼働時間に含める 1：後作業（CC紐づけあり） 時間を稼働時間に含める |
No | query | string | -- |
| Authorization |
APIトークン認証方式の場合に用います | ''Tokenトークン文字列'の形式で入力します | Yes | header | string | -- |
● 実行形式
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★契約BIZETLサーバFQDN★:8000/public/api/v1/report/agent/call_status?★リクエストパラメータ★"
※★印の部分は、ご利用内容、取得内容により任意の値を入力ください。
● 入力サンプル
curl -X GET --header "Accept: application/json" --header "Authorization: Token d6357156532a940baea9e0012bab1e55e9e4cb51e6c9a352e16206d053303929c9e52cd4609a4bbf" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/report/agent/call_status?queue_ids=10001&category=0&ringnoanswer_sec=0&account_ids=10001,10002,10003&account_status_ids=1,2,3&occupancy_status_ids=&queue_specific_account_status_ids=1&queue_specific_occupancy_status_ids="
2.4 レスポンスコード
レポート取得APIのレスポンスコードは以下となります。
| HTTP Status Code | Reason | 説明 |
|---|---|---|
| 200 | Successful Operation | 正常終了（成功） |
| 400 | Bad Request | 不正なリクエスト |
| 401 | Unauthorized | 認証失敗 |
| 404 | Not Found | 対象が存在しません |
| 429 | TooManyRequest | バースト上限の超過 |
| 500 | Internal Server Error | システム障害 |
2.5 ヘッダー
レポート取得APIのヘッダー情報は以下となります。
{
"Access-Control-Allow-Credentials": "true"
"Access-Control-Allow-Headers": "Origin, Content-Type, Authorization, X-Auth-Token, x-xsrf-token"
"Access-Control-Allow-Methods": "GET, POST, PUT, DELETE"
"Access-Control-Allow-Origin": "*"
"Cache-Control": "no-cache, private"
"Cache-Control": "no-store"
"Cache-Control": "no-store"
"Connection": "keep-alive"
"Content-Encoding": "gzip"
"Content-Security-Policy": "default-src 'self'; style-src 'self' 'unsafe-inline'; font-src 'self' data:; script-src 'self' 'unsafe-inline'; media-src 'self' blob:; connect-src 'self' blob": "ws": "wss:;; img-src 'self' data": "blob:;"
"Content-Type": "application/json"
"Date": "Wed, 22 Mar 2023 01:49:58 GMT"
"Permissions-Policy": "cross-origin-isolated=(self), sync-xhr=(self), accelerometer=(), autoplay=(), camera=(), display-capture=(), document-domain=(), encrypted-media=(), fullscreen=(), geolocation=(), gyroscope=(), keyboard-map=(), magnetometer=(), midi=(), payment=(), picture-in-picture=(), publickey-credentials-get=(), screen-wake-lock=(), usb=(), web-share=(), xr-spatial-tracking=(), clipboard-read=(), clipboard-write=(), hid=(), idle-detection=(), serial=()"
"Referrer-Policy": "no-referrer"
"Server": "nginx"
"Strict-Transport-Security": "max-age=31536000; includeSubDomains"
"Transfer-Encoding": "chunked"
"Vary": "Accept-Encoding"
"X-Account-ID": "1"
"X-Content-Type-Options": "nosniff"
"X-Frame-Options": "DENY"
"X-RateLimit-Limit": "300"
"X-RateLimit-Remaining": "297"
"X-Robots-Tag": "noindex"
"X-XSS-Protection": "1; mode=block"
}
2.6 レスポンスボディ
サマリーレポートのレスポンスボディは以下となります。
● 取得に成功した場合の例
{
"account_id": "10001",
"account_name": "USER1",
"account_kana": "デフォルトユーザ1",
"login_cnt": "0",
"login_time": "00:00:00",
"occupancy": "---",
"comp": "0",
"moh": "0",
"noanswer": "0",
"dump": "0",
"totaltalk": "00:00:00",
"talkavg": "00:00:00",
"talkmax": "00:00:00",
"totalmoh": "00:00:00",
"mohavg": "00:00:00",
"mohmax": "00:00:00",
"totalcnt": "0",
"totalsum": "00:00:00",
"processavg": "00:00:00",
"processmax": "00:00:00",
"processcum": "00:00:00",
"cnt_1": 0,
"avg_1": "00:00:00",
"sum_1": "00:00:00",
"cnt_2": 0,
"avg_2": "00:00:00",
"sum_2": "00:00:00",
"cnt_3": 0,
"avg_3": "00:00:00",
"sum_3": "00:00:00",
"cnt_1_qs": 0,
"avg_1_qs": "00:00:00",
"sum_1_qs": "00:00:00"
}
● 取得に失敗した場合の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
2.7 レスポンスパラメータ
通話・ステータスレポートのレスポンスパラメータは以下となります。
| account_id | 画面上での該当項目：なし ※取得対象のアカウントIDです |
|---|---|
| account_name | 画面での該当項目：アカウント ※取得対象のアカウントの名前です |
| account_kana | 画面での該当項目：アカウント名 ※取得対象のアカウント名前（かな）です |
| login_cnt |
画面での該当項目：ログイン時間・回数 |
| login_time | 画面での該当項目：ログイン時間・時間 ・エージェントがログインしていた合計時間です |
| occupancy | 画面での該当項目：稼働率（％） ・ログイン時間を元に稼働率 ：(通話時間＋設定ステータス時間) ÷ ログイン時間を算出します ※設定ステータス時間は詳細設定タブで後処理、離席中、休憩中、追加したステータスを含めるかどうかを設定してください ※設定した集計期間内でログイン → ログオフ操作を行っていない場合は、ログイン時間が未確定となる為、正常にデータを取得できません。 ※ログイン→ログオフ操作によって確定したログイン時間が(通話時間＋設定ステータス時間)よりも短い場合など値が 100％を超える可能があります。 |
| comp | 画面での該当項目：通話累計・通話数 ・エージェントがお客様との通話を終了した呼数です ※通話終了イベントが発生した時点で集計します |
| moh | 画面での該当項目：保留累計・保留数 ・エージェントが通話を保留した回数です ※保留した日時で集計します |
| noanswer | 画面での該当項目：応答不能回数 ・エージェントが応答できなかった呼び出し回数です ・応答不能イベントが発生した時点で集計します ・応答不能は次の場合に 1回としてカウントします。 ①コールセンター設定のエージェント呼び出し設定「タイムアウト（秒）」の秒数呼び出したが応答しなかった場合 ②電話着信時にステータスが「受付可」であるが電話機(ソフトフォン)を起動していなかった場合 ③ステータスが受付可のまま、コールセンター着信以外の通話（内線・外線）中で、応答できなかった場合 ④エージェント側で応答拒否した場合 ⑤エージェントが応答する前にお客様が電話を切った（放棄呼）場合 |
| dump | 画面での該当項目：なし エージェントがエージェント向けガイダンス中に通話を切断した回数です |
| totaltalk | 画面上での該当項目：通話累計・累計 ・エージェントの総通話時間です ・通話終了イベントが発生した日時で集計します |
| talkavg | 画面での該当項目：通話累計・平均 ・エージェントの平均通話時間です ・通話終了イベントが発生した日時で集計小数点以下は切り捨てて表示します |
| talkmax | 画面での該当項目：なし ・エージェントの最大通話時間です ※通話終了イベントが発生した日時で集計します |
| totalmoh | 画面での該当項目：保留累計・累計 ・エージェントが通話を保留して通話に戻るまでの総保留時間です ※保留を解除した日時で集計します |
| mohavg | 画面での該当項目：保留累計・平均 ・エージェントが通話を保留して通話に戻るまでの平均保留時間です ※保留を解除した日時で集計します ※小数点以下は切り捨てて表示します |
| mohmax | 画面での該当項目：なし ・エージェントが通話を保留して通話に戻るまでの最大時間 ・保留を解除した日時で集計する |
| totalcnt | 画面での該当項目：受付不可累計・回数 ・エージェントが受付不可のステータス（後作業・離席中・休憩中・追加ステータス）にした回数の累計です |
| totalsum | 画面での該当項目：受付不可累計・累計 ・エージェントで受付不可であったステータス（後作業・離席中・休憩中・追加ステータス）の総受付不可時間です |
| processavg | 画面上での該当項目：処理時間・平均 ・集計対象で選択されているエージェントの通話時間＋後作業時間の平均です ・通話時間は、通話終了イベントが発生した日時で集計します ・後作業時間は、後作業ステータスから別ステータスに変更された日時で集計します |
| processmax | 画面上での該当項目：処理時間・最大 ・集計対象で選択されているエージェントの通話時間＋後作業時間の最大です ・通話時間は、通話終了イベントが発生した日時で集計します ・後作業時間は、後作業ステータスから別ステータスに変更された日時で集計します |
| processcum | 画面上での該当項目：処理時間・累計 ・対象コールセンターに所属する全エージェントの通話時間＋後作業時間の累計です ・通話時間は、通話終了イベントが発生した日時で集計します ・後作業時間は、後作業ステータスから別ステータスに変更された日時で集計します |
| cnt_1 | 画面での該当項目：後作業（CC紐づけなし）・回数 ・エージェントが後作業ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します ※手動ステータス変更によりコールセンターと紐づかない後作業のみが対象です |
| avg_1 | 画面での該当項目：後作業（CC紐づけなし）・平均 ・エージェントが後作業ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※手動ステータス変更によりコールセンターと紐づかない後作業のみが対象です |
| sum_1 | 画面での該当項目：後作業（CC紐づけなし）・累計 ・エージェントが後作業ステータスにしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※手動ステータス変更によりコールセンターと紐づかない後作業のみが対象です |
| cnt_2 | 画面での該当項目：休憩中・回数 ・エージェントが休憩中ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| avg_2 | 画面での該当項目：休憩中・平均 ・エージェントが休憩中ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| sum_2 | 画面での該当項目：休憩中・累計 ・エージェントが休憩中ステータスにしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計する |
| cnt_3 | 画面での該当項目：離席中・回数 ・エージェントが離席中ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| avg_3 | 画面での該当項目：離席中・平均 ・エージェントが離席中ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| sum_3 | 画面での該当項目：離席中・累計 ・エージェントが離席中ステータスにしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| cnt_｛ユーザ作成ステータス｝ | 画面での該当項目：｛ユーザ作成ステータス｝・回数 ・エージェントが｛ユーザ作成ステータス｝に切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| avg_｛ユーザ作成ステータス｝ | 画面での該当項目：｛ユーザ作成ステータス｝・平均 ・エージェントが｛ユーザ作成ステータス｝にしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※小数点以下は切り捨てて表示します |
| sum_｛ユーザ作成ステータス｝ | 画面での該当項目：｛ユーザ作成ステータス｝・累計 ・エージェントが｛ユーザ作成ステータス｝にしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| cnt_1_qs | 画面での該当項目：後作業（CC紐づけあり）・回数 ・エージェントが後作業ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します ※自動的に後作業にするによりコールセンターと紐づいた後作業のみが対象です |
| avg_1_qs | 画面での該当項目：後作業（CC紐づけあり）・平均 ・エージェントが後作業ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※自動的に後作業にするによりコールセンターと紐づいた後作業のみが対象です |
| sum_1_qs | 画面での該当項目：後作業（CC紐づけあり）・累計 ・エージェントが後作業ステータスにしていた総時間 ※対象ステータスから他のステータスに切り替えた日時で集計します ※自動的に後作業にするによりコールセンターと紐づいた後作業のみが対象です |
2.8 エラー仕様
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| from | 開始日時より前の終了日時を設定する | ValidateException | VALIDATE_ERROR | greater than to |
| 開始日時から終了日時までの範囲が2年より広い状態 | 集計期間は2年(730日)以内で指定してください | |||
| to | 開始日時より前の終了日時を設定する | ValidateException | VALIDATE_ERROR | greater than to |
| 開始日時から終了日時までの範囲が2年より広い状態 | 集計期間は2年(730日)以内で指定してください | |||
| category | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「0:コールセンター」「1:業務ラベル」以外を入力した場合 | 0〜1までにしてください | |||
| queue_ids | 未入力 (集計対象未入力または集計対象プルダウンでコールセンターを選択時) |
ValidateException | VALIDATE_ERROR | report_queue_i_ds:値がありません |
| 半角数字以外を入力した場合 (集計対象未入力または集計対象プルダウンでコールセンターを選択時） |
引数が数値でありません: '{入力文字列}' | |||
| コールセンター一覧に存在しないコールセンターIDを入力した場合 (集計対象未入力または集計対象プルダウンでコールセンターを選択時） |
EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| business_ids | 未入力 (集計対象未入力または集計対象プルダウンで業務ラベルを選択時) |
ValidateException | VALIDATE_ERROR | report_business_i_ds:値がありません |
| 半角数字以外を入力した場合 (集計対象未入力または集計対象プルダウンで業務ラベルを選択時） |
引数が数値でありません: '{入力文字列}' | |||
| 業務ラベル一覧に存在しない業務ラベルIDを入力した場合 (集計対象未入力または集計対象プルダウンで業務ラベルを選択時） |
EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| account_ids | 未入力 | ValidateException | VALIDATE_ERROR | report_queue_i_ds:値がありません |
| 半角数字以外を入力した場合 | 引数が数値でありません: '{入力文字列}' | |||
| アカウント一覧に存在しないアカウントIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| ringnoanswer_sec | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「0〜300」以外を入力した場合 | ValidateException | 0〜300までにしてください | ||
| account_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| occupancy_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| queue_specific_account_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| queue_specific_occupancy_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| Authorization | トークンが未入力の場合（Tokenの入力もされていない） | AuthenticationException | UNAUTHENTICATED | Unauthenticated: cause=unknown auth method. |
| 認証に失敗した場合 ※「Token」のみ入力した場合 |
Unauthenticated: method=personal_token, cause=invalid request | |||
| 認証に失敗した場合 ※「Token {誤ったToken文字列}」のみ入力した場合 |
Unauthenticated: method=personal_token, cause=invalid token. | |||
| ライセンス無効 | Unauthenticated: method=personal_token, cause=api license disabled | |||
| -- | レポート取得APIライセンスがOFFの状態で通話・ステータスレポート情報取得APIを実行した場合 | AuthorizationException | FORBIDDEN | This action is unauthorized. |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
3.日時・曜日別レポートの取得
3.1 API仕様
URI schemeは通話・ステータスレポートの「2.1 API仕様」と同様です。
3.2 リクエスト方式
日時・曜日別レポートのデータ取得時のリクエスト方式は以下となります。
| 認証方式 | HTTPメソッド | URI | 備考 |
|---|---|---|---|
| APIトークン認証方式 | GET | /public/api/v1/report/agent/datewise |
APIトークンによるアカウント認証が必要です。 |
3.3 リクエストパラメータ
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| from | 集計開始日時を指定します | 画面での該当項目：集計開始日時 画面での該当項目は必須項目です |
No | query | string |
当日0時 yyyy/mm/dd hh:mm |
| to | 集計終了日時を指定します | 画面での該当項目：集計終了日時 画面での該当項目は必須項目です |
No | query | string |
翌日0時 (当日の24時) yyyy/mm/dd hh:mm |
| category | 集計対象を選択します | 画面での該当項目：集計対象 0：コールセンター 1：業務ラベル |
No | query | integer |
0 ※0～1で入力ください。 |
| grouptype |
集計単位を選択します | 画面での該当項目：集計単位 1：月 2：日 3：時 4：分 5：曜日 |
No | query | integer |
3 ※1～5で入力ください。 |
| queue_ids | コールセンターを選択します | 画面での該当項目：コールセンター 集計対象プルダウンでコールセンターを選択時 |
Yes: 集計対象未入力または集計対象プルダウンでコールセンターを選択時 No: 集計対象プルダウンでコールセンターを選択時 |
query | string | -- |
| business_ids | 業務ラベルを選択します | 画面での該当項目：業務ラベル 集計対象プルダウンで業務ラベルを選択時 |
Yes: 集計対象プルダウンで業務ラベルを選択時 No: 集計対象未入力または集計対象プルダウンでコールセンターを選択時 |
query | string | -- |
| account_ids | エージェントを選択します | 画面での該当項目：エージェント | Yes | query | string | -- |
| ringnoanswer_sec | 応答不能集計秒数を選択します | 画面での該当項目：応答不能集計秒数 | No | query | integer | 0 |
| account_status_ids | ステイタスを選択します | 画面での該当項目：表示設定のステイタス 1：後作業（CC紐づけなし） 2：休憩中 3：離席中 |
No | query | string | -- |
| occupancy_status_ids | 稼働率の算出方法種別を選択します | 画面での該当項目：詳細設定の稼働率の算出方法種別 1：後作業（CC紐づけなし） 時間を通話処理時間に含める 2：休憩中 時間を通話処理時間に含める 3：離席中 時間を通話処理時間に含める |
No | query | string | -- |
| queue_specific_account_status_ids | 自動変更ステータスを含む | 画面での該当項目：1000：後作業（CC紐づけあり） 1：後作業（CC紐づけあり） |
No | query | string | -- |
| queue_specific_occupancy_status_ids | 自動変更ステータスを稼働率に含む | 画面での該当項目：1000：後作業（CC紐づけあり） 時間を通話処理時間に含める 1：後作業（CC紐づけあり） 時間を通話処理時間に含める |
No | query | string | -- |
| Authorization |
APIトークン認証方式の場合に用います | ''Tokenトークン文字列'の形式で入力します | Yes | header | string | -- |
● 実行形式
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★契約BIZETLサーバFQDN★:8000/public/api/v1/report/agent/datewise?★リクエストパラメータ★"
※★印の部分は、ご利用内容、取得内容により任意の値を入力ください。
● 入力サンプル
curl -X GET --header "Accept: application/json" --header "Authorization: Token d6357156532a940baea9e0012bab1e55e9e4cb51e6c9a352e16206d053303929c9e52cd4609a4bbf" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/report/agent/datewise?queue_ids=10001&category=0&ringnoanswer_sec=0&account_ids=10001,10002,10003&account_status_ids=1,2,3&occupancy_status_ids=&queue_specific_account_status_ids=1&queue_specific_occupancy_status_ids=&grouptype=3"
3.4 レスポンスコード
日時・曜日別レポートのレスポンスコードは通話ステータスレポートの「2.4 レスポンスコード」と同様です。
3.5 ヘッダー
日時・曜日別レポートのヘッダー情報は通話ステータスレポートの「2.5 ヘッダー」と同様です。
3.6 レスポンスボディ
日時・曜日別レポートのレスポンスボディは以下となります。
● 取得に成功した場合の例
{
"login_cnt": "0",
"login_time": "00:00:00",
"occupancy": "---",
"comp": "0",
"moh": "0",
"noanswer": "0",
"dump": "0",
"totaltalk": "00:00:00",
"talkavg": "00:00:00",
"talkmax": "00:00:00",
"totalmoh": "00:00:00",
"mohavg": "00:00:00",
"mohmax": "00:00:00",
"totalcnt": "0",
"totalsum": "00:00:00",
"processavg": "00:00:00",
"processmax": "00:00:00",
"processcum": "00:00:00",
"time": "00:00",
"cnt_1": 0,
"avg_1": "00:00:00",
"sum_1": "00:00:00",
"cnt_2": 0,
"avg_2": "00:00:00",
"sum_2": "00:00:00",
"cnt_3": 0,
"avg_3": "00:00:00",
"sum_3": "00:00:00",
"cnt_1_qs": 0,
"avg_1_qs": "00:00:00",
"sum_1_qs": "00:00:00"
}
● 取得に失敗した場合の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
3.7 レスポンスパラメータ
日時・曜日別レポートのレスポンスパラメータは以下となります。
| login_cnt |
画面での該当項目：ログイン時間・回数 |
|---|---|
| login_time | 画面での該当項目：ログイン時間・時間 ・エージェントがログインしていた合計時間です |
| occupancy | 画面での該当項目：稼働率（％） ・ログイン時間を元に稼働率 ：(通話時間＋設定ステータス時間) ÷ ログイン時間を算出します ※設定ステータス時間は詳細設定タブで後処理、離席中、休憩中、追加したステータスを含めるかどうかを設定してください ※設定した集計期間内でログイン → ログオフ操作を行っていない場合は、ログイン時間が未確定となる為、正常にデータを取得できません。 ※ログイン→ログオフ操作によって確定したログイン時間が(通話時間＋設定ステータス時間)よりも短い場合など値が 100％を超える可能があります。 |
| comp | 画面での該当項目：通話累計・通話数 ・エージェントがお客様との通話を終了した呼数です ※通話終了イベントが発生した時点で集計します |
| moh | 画面での該当項目：保留累計・保留数 ・エージェントが通話を保留した回数です ※保留した日時で集計します |
| noanswer | 画面での該当項目：応答不能回数 ・エージェントが応答できなかった呼び出し回数です ・応答不能イベントが発生した時点で集計します ・応答不能は次の場合に 1回としてカウントします。 ①コールセンター設定のエージェント呼び出し設定「タイムアウト（秒）」の秒数呼び出したが応答しなかった場合 ②電話着信時にステータスが「受付可」であるが電話機(ソフトフォン)を起動していなかった場合 ③ステータスが受付可のまま、コールセンター着信以外の通話（内線・外線）中で、応答できなかった場合 ④エージェント側で応答拒否した場合 ⑤エージェントが応答する前にお客様が電話を切った（放棄呼）場合 |
| dump | 画面での該当項目：なし エージェントがエージェント向けガイダンス中に通話を切断した回数です |
| totaltalk | 画面上での該当項目：通話累計・累計 ・エージェントの総通話時間です ・通話終了イベントが発生した日時で集計します |
| talkavg | 画面での該当項目：通話累計・累計 ・エージェントの総通話時間です ※通話終了イベントが発生した時点で集計します |
| talkmax | 画面での該当項目：なし ・エージェントの最大通話時間です ※通話終了イベントが発生した日時で集計します |
| totalmoh | 画面での該当項目：保留累計・累計 ・エージェントが通話を保留して通話に戻るまでの総保留時間です ※保留を解除した日時で集計します |
| mohavg | 画面での該当項目：保留累計・平均 ・エージェントが通話を保留して通話に戻るまでの平均保留時間です ※保留を解除した日時で集計します ※小数点以下は切り捨てて表示します |
| mohmax | 画面での該当項目：なし ・エージェントが通話を保留して通話に戻るまでの最大時間 ・保留を解除した日時で集計する |
| totalcnt | 画面での該当項目：受付不可累計・回数 ・エージェントが受付不可のステータス（後作業・離席中・休憩中・追加ステータス）にした回数の累計です |
| totalsum | 画面での該当項目：受付不可累計・累計 ・エージェントで受付不可であったステータス（後作業・離席中・休憩中・追加ステータス）の総受付不可時間です |
| processavg |
画面上での該当項目：処理時間・平均 ・集計対象で選択されているエージェントの通話時間＋後作業時間の平均です ・通話時間は、通話終了イベントが発生した日時で集計します ・後作業時間は、後作業ステータスから別ステータスに変更された日時で集計します |
| processmax |
画面上での該当項目：処理時間・最大 ・集計対象で選択されているエージェントの通話時間＋後作業時間の最大です ・通話時間は、通話終了イベントが発生した日時で集計します ・後作業時間は、後作業ステータスから別ステータスに変更された日時で集計します |
| processcum |
画面上での該当項目：処理時間・累計 ・対象コールセンターに所属する全エージェントの通話時間＋後作業時間の累計です ・通話時間は、通話終了イベントが発生した日時で集計します ・後作業時間は、後作業ステータスから別ステータスに変更された日時で集計します |
| time | 画面上での該当項目：日時/曜日 ・集計単位で月・日・時間・時間（10 分）を選択した場合は日時、曜日を選択した場合は曜日を表示します |
| cnt_1 | 画面での該当項目：後作業（CC紐づけなし）・回数 ・エージェントが後作業ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します ※手動ステータス変更によりコールセンターと紐づかない後作業のみが対象です |
| avg_1 | 画面での該当項目：後作業（CC紐づけなし）・平均 ・エージェントが後作業ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※手動ステータス変更によりコールセンターと紐づかない後作業のみが対象です |
| sum_1 | 画面での該当項目：後作業（CC紐づけなし）・累計 ・エージェントが後作業ステータスにしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※手動ステータス変更によりコールセンターと紐づかない後作業のみが対象です |
| cnt_2 | 画面での該当項目：休憩中・回数 ・エージェントが休憩中ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| avg_2 | 画面での該当項目：休憩中・平均 ・エージェントが休憩中ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| sum_2 | 画面での該当項目：休憩中・累計 ・エージェントが休憩中ステータスにしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計する |
| cnt_3 | 画面での該当項目：離席中・回数 ・エージェントが離席中ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| avg_3 | 画面での該当項目：離席中・平均 ・エージェントが離席中ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| sum_3 | 画面での該当項目：離席中・累計 ・エージェントが離席中ステータスにしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| cnt_｛ユーザ作成ステータス｝ | 画面での該当項目：｛ユーザ作成ステータス｝・回数 ・エージェントが｛ユーザ作成ステータス｝に切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| avg_｛ユーザ作成ステータス｝ | 画面での該当項目：｛ユーザ作成ステータス｝・平均 ・エージェントが｛ユーザ作成ステータス｝にしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※小数点以下は切り捨てて表示します |
| sum_｛ユーザ作成ステータス｝ | 画面での該当項目：｛ユーザ作成ステータス｝・累計 ・エージェントが｛ユーザ作成ステータス｝にしていた総時間です ※対象ステータスから他のステータスに切り替えた日時で集計します |
| cnt_1_qs | 画面での該当項目：後作業（CC紐づけあり）・回数 ・エージェントが後作業ステータスに切り替えた回数です ※対象ステータスから他のステータスに切り替えた日時で集計します ※自動的に後作業にするによりコールセンターと紐づいた後作業のみが対象です |
| avg_1_qs | 画面での該当項目：後作業（CC紐づけあり）・平均 ・エージェントが後作業ステータスにしていた平均時間です ※対象ステータスから他のステータスに切り替えた日時で集計します ※自動的に後作業にするによりコールセンターと紐づいた後作業のみが対象です |
| sum_1_qs | 画面での該当項目：後作業（CC紐づけあり）・累計 ・エージェントが後作業ステータスにしていた総時間 ※対象ステータスから他のステータスに切り替えた日時で集計します ※自動的に後作業にするによりコールセンターと紐づいた後作業のみが対象です |
3.8 エラー仕様
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| from | 開始日時より前の終了日時を設定する | ValidateException | VALIDATE_ERROR | greater than to |
| 開始日時から終了日時までの範囲が2年より広い状態 | 集計期間は2年(730日)以内で指定してください | |||
| to | 開始日時より前の終了日時を設定する | ValidateException | VALIDATE_ERROR | greater than to |
| 開始日時から終了日時までの範囲が2年より広い状態 | 集計期間は2年(730日)以内で指定してください | |||
| category | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「0:コールセンター」「1:業務ラベル」以外を入力した場合 | 0〜1までにしてください | |||
| grouptype | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「1:月」「2:日」「3:時」「4:分」「5:曜日」以外を入力した場合 | 1〜5までにしてください | |||
| queue_ids | 未入力 (集計対象未入力または集計対象プルダウンでコールセンターを選択時) |
ValidateException | VALIDATE_ERROR | report_queue_i_ds:値がありません |
| 半角数字以外を入力した場合 (集計対象未入力または集計対象プルダウンでコールセンターを選択時） |
引数が数値でありません: '{入力文字列}' | |||
| コールセンター一覧に存在しないコールセンターIDを入力した場合 (集計対象未入力または集計対象プルダウンでコールセンターを選択時） |
EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| business_ids | 未入力 (集計対象未入力または集計対象プルダウンで業務ラベルを選択時) |
ValidateException | VALIDATE_ERROR | report_business_i_ds:値がありません |
| 半角数字以外を入力した場合 (集計対象未入力または集計対象プルダウンで業務ラベルを選択時） |
引数が数値でありません: '{入力文字列}' | |||
| 業務ラベル一覧に存在しない業務ラベルIDを入力した場合 (集計対象未入力または集計対象プルダウンで業務ラベルを選択時） |
EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| account_ids | 未入力 | ValidateException | VALIDATE_ERROR | report_queue_i_ds:値がありません |
| 半角数字以外を入力した場合 | 引数が数値でありません: '{入力文字列}' | |||
| アカウント一覧に存在しないアカウントIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| ringnoanswer_sec | 半角数字以外を入力した場合 |
ValidateException |
VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「0〜300」以外を入力した場合 | 0〜300までにしてください | |||
| account_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| occupancy_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| queue_specific_account_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| queue_specific_occupancy_status_ids | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| ステータス一覧に存在しないステータスIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| Authorization | トークンが未入力の場合（Tokenの入力もされていない） | AuthenticationException | UNAUTHENTICATED | Unauthenticated: cause=unknown auth method. |
| 認証に失敗した場合 ※「Token」のみ入力した場合 |
Unauthenticated: method=personal_token, cause=invalid request | |||
| 認証に失敗した場合 ※「Token {誤ったToken文字列}」のみ入力した場合 |
Unauthenticated: method=personal_token, cause=invalid token. | |||
| ライセンス無効 | Unauthenticated: method=personal_token, cause=api license disabled | |||
| -- | レポート取得APIライセンスがOFFの状態で通話・ステータスレポート情報取得APIを実行した場合 | AuthorizationException | FORBIDDEN | This action is unauthorized. |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
4.APIリクエスト数の消費について
BIZTEL API（レポート取得API）のライセンス消費数は以下となります。
| 認証方式 | ライセンス消費数 | 備考 |
|---|---|---|
| APIトークン認証方式 | １リクエストにつき、１消費 |
累積APIリクエスト数、累積APIレスポンスオブジェクト数ともに１づつ消費します。 |