※本マニュアルは、BIZTELバージョン 3.9.Xまでをご利用のユーザ様向けです。
BIZTELバージョン 3.10.X以降をご利用の場合は、「12.レポート取得API（電話番号レポート）※3.10.X以降」を参照ください。
| 目的 |
外部システムとBIZTELを連携することで、エージェントの発信通話に関する通話レポートの集計値を外部システムに連携することが可能です。 |
|---|---|
| 対象プラン |
|
| 用語 |
【WebAPI】 汎用的なWeb技術を利用し、インターネットを介して外部システムとの連携を容易にする仕組みです。 【BIZTEL API】 BIZTELが公開するAPIを示します。 |
| ポイント |
・本機能は、BIZTELバージョン 3.8.0 以降で利用可能です。 ・本機能をご利用いただく場合、「レポート取得API」のライセンス契約が必要です。 ・月間のAPIリクエスト数、APIレスポンスオブジェクト数の上限は、各100,000件となります。 |
・本マニュアルはHTML/PHP(PCRE正規表現等)/WebAPIの基礎的な技術知識がある、WEB系開発者様やCRMベンダー様を対象にしております。
目次
1.レポート取得APIの基本機能
レポート取得APIは、BIZTELと外部システムの連携により、外部システムからBIZTELの各種レポートの内容を取得可能とします。
取得可能なレポートは以下となります。
・コールセンターレポート（4.レポート取得API（コールセンターレポート）※3.9.Xまでを参照ください）
・エージェントレポート（5.レポート取得API（エージェントレポート）※3.9.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/outbound/dialed_call_status |
APIトークンによるアカウント認証が必要です。 |
2.3 リクエストパラメータ
通話・ステータスレポート（電話番号別）のリクエストパラメータは以下となります。
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| from | 集計開始日時を指定します |
画面での該当項目：集計開始日時 |
No | query | string |
当日0時 yyyy/mm/dd hh:mm |
| to | 集計終了日時を指定します | 画面での該当項目：集計終了日時 ※画面での該当項目は必須項目です |
No | query | string |
翌日0時 yyyy/mm/dd hh:mm |
| account_ids | エージェントを選択します | 画面での該当項目：エージェント | Yes | query | string | -- |
| phone_number_ids | 発信番号を選択します | 画面での該当項目：発信番号 | Yes | query | string | -- |
| Authorization | APIトークン認証方式の場合に用います | ''Tokenトークン文字列'と入力します | Yes | header | string | -- |
● 実行形式
macOSのコンソールで実行する場合の例です。
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★契約BIZETLサーバFQDN★:8000/public/api/v1/report/outbound/dialed_call_status?★リクエストパラメータ★"
● 入力サンプル
curl -X GET --header "Accept: application/json" --header "Authorization: Token d6357156532a940baea9e0012bab1e55e9e4cb51e6c9a352e16206d053303929c9e52cd4609a4bbf" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/report/outbound/dialed_call_status?account_ids=10001,10002,10003&phone_number_ids=10001,10002"
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 ヘッダー
通話・ステータスレポート（電話番号別）取得時のヘッダーは以下となります。
{
"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 レスポンスボディ
通話・ステータスレポート（電話番号別）取得時のレスポンスボディは以下となります。
● 取得に成功した場合の例
"dialedSummary": [
{
"did": "0330000002",
"sip_user_name": "1002",
"extension_name": "デフォルト端末2",
"call_cnt": "3",
"connected_cnt": "0",
"abandon_cnt": "0",
"connected_rate": "0",
"talk_time_min": "0",
"talk_time_avg": "0",
"talk_time_max": "0",
"talk_time_sum": "0",
"wait_time_min": "0",
"wait_time_avg": "0",
"wait_time_max": "0",
"wait_time_sum": "0"
}
],
"dialedData": [
{
"did": "0330000002",
"account_id": "10001",
"account_name": "USER1",
"account_kana": "デフォルトユーザ1",
"sip_user_name": "1002",
"extension_name": "デフォルト端末2",
"call_cnt": "1",
"connected_cnt": "0",
"abandon_cnt": "0",
"connected_rate": "0",
"talk_time_min": "0",
"talk_time_avg": "0",
"talk_time_max": "0",
"talk_time_sum": "0",
"wait_time_min": "0",
"wait_time_avg": "0",
"wait_time_max": "0",
"wait_time_sum": "0"
}
]
● 取得に失敗した場合の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
2.7 レスポンスパラメータ
通話・ステータスレポート（電話番号別）のレスポンスパラメータは以下となります。
| パラメータ | 説明 | |
|---|---|---|
| dialedSummary | did | 画面上での該当項目：発信番号 ・発信時の通知番号です |
| sip_user_name |
画面での該当項目：内線番号 ・発信した外線番号に紐づく内線番号です |
|
| extension_name |
画面での該当項目：名称 ・発信した内線番号の名称です |
|
| call_cnt | 画面での該当項目：発信数 ・発信を開始した呼数です ・アウトバウンドイベントが発生（発信を開始）した日時で集計します |
|
| connected_cnt | 画面での該当項目：コンタクト数 ・ 発信先が応答した呼数です ・ アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| abandon_cnt | 画面での該当項目：未コンタクト数 ・発信先が電話に応答しなかった呼数です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| connected_rate | 画面での該当項目：コンタクト率(%) ・発信を開始した呼数の内、発信先が応答した呼数の割合を「コンタクト数÷発信数」で算出します |
|
| talk_time_min | 画面での該当項目：コンタクト通話集計・最小 ・発信が応答してから電話を切るまでの最小通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_avg | 画面での該当項目：コンタクト通話集計・平均 ・発信が応答してから電話を切るまでの平均通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| talk_time_max | 画面での該当項目：コンタクト通話集計・最大 ・発信が応答してから電話を切るまでの最大通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_sum | 画面での該当項目：コンタクト通話集計・合計 ・発信が応答してから電話を切るまでの合計通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_min | 画面での該当項目：コンタクトまでの所要時間・最小 ・発信を開始してから発信先が応答するまでに要した最小時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_avg | 画面での該当項目：コンタクトまでの所要時間・平均 ・発信を開始してから発信先が応答するまでに要した平均時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| wait_time_max | 画面での該当項目：コンタクトまでの所要時間・最大 ・発信を開始してから発信先が応答するまでに要した最大時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_sum | 画面での該当項目：コンタクトまでの所要時間・合計 ・発信を開始してから発信先が応答するまでに要した合計時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| dialedData | did | 画面上での該当項目：発信番号 ・発信時の通知番号です |
| account_id | 画面上での該当項目：なし ・発信したアカウントのIDです |
|
| account_name | 画面上での該当項目：アカウント ・発信したアカウントです |
|
| account_kana | 画面上での該当項目：アカウント名 ・発信したアカウントの名前です |
|
| sip_user_name |
画面での該当項目：内線番号 ・発信した外線番号に紐づく内線番号です |
|
| extension_name |
画面での該当項目：名称 ・発信した内線番号の名称です |
|
| call_cnt | 画面での該当項目：発信数 ・発信を開始した呼数です ・アウトバウンドイベントが発生（発信を開始）した日時で集計します |
|
| connected_cnt | 画面での該当項目：コンタクト数 ・ 発信先が応答した呼数です ・ アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| abandon_cnt | 画面での該当項目：未コンタクト数 ・発信先が電話に応答しなかった呼数です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| connected_rate | 画面での該当項目：コンタクト率(%) ・発信を開始した呼数の内、発信先が応答した呼数の割合を「コンタクト数÷発信数」を算出します |
|
| talk_time_min | 画面での該当項目：コンタクト通話集計・最小 ・発信が応答してから電話を切るまでの最小通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_avg | 画面での該当項目：コンタクト通話集計・平均 ・発信が応答してから電話を切るまでの平均通話時間 ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計される ・小数点以下は切り捨して表示 |
|
| talk_time_max | 画面での該当項目：コンタクト通話集計・最大 ・発信が応答してから電話を切るまでの最大通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_sum | 画面での該当項目：コンタクト通話集計・合計 ・発信が応答してから電話を切るまでの合計通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_min | 画面での該当項目：コンタクトまでの所要時間・最小 ・発信を開始してから発信先が応答するまでに要した最小時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_avg | 画面での該当項目：コンタクトまでの所要時間・平均 ・発信を開始してから発信先が応答するまでに要した平均時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| wait_time_max | 画面での該当項目：コンタクトまでの所要時間・最大 ・発信を開始してから発信先が応答するまでに要した最大時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_sum | 画面での該当項目：コンタクトまでの所要時間・合計 ・発信を開始してから発信先が応答するまでに要した合計時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
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日)以内で指定してください | |||
| account_ids | 未入力 | ValidateException | VALIDATE_ERROR |
report_account_i_ds:値がありません |
| 半角数字以外を入力した場合 | 引数が数値でありません: '{入力文字列}' | |||
| アカウント一覧に存在しないアカウントIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| phone_number_ids | 未入力 | ValidateException | VALIDATE_ERROR | report_dialed_number_i_ds:値がありません |
| 半角数字以外を入力した場合 | 引数が数値でありません: '{入力文字列}' | |||
| 電話番号一覧に存在しない電話番号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基本仕様
通話・ステータスレポート（エージェント別）のAPI仕様は「2.1 API基本仕様」と同様です。
3.2 リクエスト方式
通話・ステータスレポート（エージェント別）のリクエスト方式は以下の通りです。
| 認証方式 | HTTPメソッド | URI | 備考 |
|---|---|---|---|
| APIトークン認証方式 | GET | /public/api/v1/report/outbound/agent_call_status |
APIトークンによるアカウント認証が必要です。 |
3.3 リクエストパラメータ
通話・ステータスレポート（エージェント別）のリクエストパラメータは「2.3 リクエストパラメータ」と同様です。
3.4 レスポンスコード
通話・ステータスレポート（エージェント別）のレスポンスコードは「2.4 レスポンスコード」と同様です。
3.5 ヘッダー
通話・ステータスレポート（エージェント別）のヘッダーは「2.5 ヘッダー」と同様です。
3.6 レスポンスボディ
通話・ステータスレポート（エージェント別）のレスポンスボディは以下となります。
● 取得に成功した場合の例
"agentSummary": [
{
"account_id": "10001",
"account_name": "USER1",
"account_kana": "デフォルトユーザ1",
"call_cnt": "1",
"connected_cnt": "0",
"abandon_cnt": "0",
"connected_rate": "0",
"talk_time_min": "0",
"talk_time_avg": "0",
"talk_time_max": "0",
"talk_time_sum": "0",
"wait_time_min": "0",
"wait_time_avg": "0",
"wait_time_max": "0",
"wait_time_sum": "0"
}
],
"agentData": [
{
"did": "0330000002",
"account_id": "10001",
"account_name": "USER1",
"account_kana": "デフォルトユーザ1",
"sip_user_name": "1002",
"extension_name": "デフォルト端末2",
"call_cnt": "1",
"connected_cnt": "0",
"abandon_cnt": "0",
"connected_rate": "0",
"talk_time_min": "0",
"talk_time_avg": "0",
"talk_time_max": "0",
"talk_time_sum": "0",
"wait_time_min": "0",
"wait_time_avg": "0",
"wait_time_max": "0",
"wait_time_sum": "0"
}
]
● 取得に失敗した場合の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
3.7 レスポンスパラメータ
通話・ステータスレポート（エージェント別）のレスポンスパラメータは以下となります。
| パラメータ | 説明 | |
|---|---|---|
| agentSummary | account_id | 画面上での該当項目：なし ・発信したアカウントのIDです |
| account_name | 画面上での該当項目：アカウント ・発信したアカウントです |
|
| account_kana | 画面上での該当項目：アカウント名 ・発信したアカウント名です |
|
| call_cnt | 画面での該当項目：発信数 ・発信を開始した呼数です ・アウトバウンドイベントが発生（発信を開始）した日時で集計します |
|
| connected_cnt | 画面での該当項目：コンタクト数 ・ 発信先が応答した呼数です ・ アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| abandon_cnt | 画面での該当項目：未コンタクト数 ・発信先が電話に応答しなかった呼数です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| connected_rate | 画面での該当項目：コンタクト率(%) 発信を開始した呼数の内、発信先が応答した呼数の割合を「コンタクト数÷発信数」を算出します |
|
| talk_time_min | 画面での該当項目：コンタクト通話集計・最小 ・発信が応答してから電話を切るまでの最小通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_avg | 画面での該当項目：コンタクト通話集計・平均 ・発信が応答してから電話を切るまでの平均通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| talk_time_max | 画面での該当項目：コンタクト通話集計・最大 ・発信が応答してから電話を切るまでの最大通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_sum | 画面での該当項目：コンタクト通話集計・合計 ・発信が応答してから電話を切るまでの合計通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_min | 画面での該当項目：コンタクトまでの所要時間・最小 ・発信を開始してから発信先が応答するまでに要した最小時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_avg | 画面での該当項目：コンタクトまでの所要時間・平均 ・発信を開始してから発信先が応答するまでに要した平均時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| wait_time_max | 画面での該当項目：コンタクトまでの所要時間・最大 ・発信を開始してから発信先が応答するまでに要した最大時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_sum | 画面での該当項目：コンタクトまでの所要時間・合計 ・発信を開始してから発信先が応答するまでに要した合計時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| agentData | did | 画面上での該当項目：発信番号 ・発信した際の通知番号です |
| account_id | 画面上での該当項目：なし ・発信したアカウントのIDです |
|
| account_name | 画面上での該当項目：アカウント ・発信したアカウントです |
|
| account_kana | 画面上での該当項目：アカウント ・発信したアカウントの名前です |
|
| sip_user_name |
画面での該当項目：内線番号 |
|
| extension_name |
画面での該当項目：名称 |
|
| call_cnt | 画面での該当項目：発信数 ・発信を開始した呼数です ・アウトバウンドイベントが発生（発信を開始）した日時で集計します |
|
| connected_cnt | 画面での該当項目：コンタクト数 ・ 発信先が応答した呼数です ・ アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| abandon_cnt | 画面での該当項目：未コンタクト数 ・発信先が電話に応答しなかった呼数です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| connected_rate | 画面での該当項目：コンタクト率(%) ・発信を開始した呼数の内、発信先が応答した呼数の割合を「コンタクト数÷発信数」で算出します |
|
| talk_time_min | 画面での該当項目：コンタクト通話集計・最小 ・発信が応答してから電話を切るまでの最小通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_avg | 画面での該当項目：コンタクト通話集計・平均 ・発信が応答してから電話を切るまでの平均通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| talk_time_max | 画面での該当項目：コンタクト通話集計・最大 ・発信が応答してから電話を切るまでの最大通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| talk_time_sum | 画面での該当項目：コンタクト通話集計・合計 ・発信が応答してから電話を切るまでの合計通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_min | 画面での該当項目：コンタクトまでの所要時間・最小 ・発信を開始してから発信先が応答するまでに要した最小時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_avg | 画面での該当項目：コンタクトまでの所要時間・平均 ・発信を開始してから発信先が応答するまでに要した平均時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
|
| wait_time_max | 画面での該当項目：コンタクトまでの所要時間・最大 ・発信を開始してから発信先が応答するまでに要した最大時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
| wait_time_sum | 画面での該当項目：コンタクトまでの所要時間・合計 ・発信を開始してから発信先が応答するまでに要した合計時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
|
3.8 エラー仕様
通話・ステータスレポート（エージェント別）のエラー仕様は「2.8 エラー仕様」と同様です。
4.日時・曜日別レポート（エージェント別）の取得
4.1 API基本仕様
日時・曜日別レポート（エージェント別）のAPI仕様は「2.1 API基本仕様」と同様です。
4.2 リクエスト方式
日時・曜日別レポート（エージェント別）のリクエスト方式は以下となります。
| 認証方式 | HTTPメソッド | URI | 備考 |
|---|---|---|---|
| APIトークン認証方式 | GET | /public/api/v1/report/outbound/datewise |
APIトークンによるアカウント認証が必要です。 |
4.3 リクエストパラメータ
日時・曜日別レポート（エージェント別）のリクエストパラメータは以下となります。
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| from | 集計開始日時を指定します |
画面での該当項目：集計開始日時 |
No | query | string |
当日0時 yyyy/mm/dd hh:mm |
| to | 集計終了日時を指定します | 画面での該当項目：集計終了日時 ※画面での該当項目は必須項目です |
No | query | string |
翌日0時 yyyy/mm/dd hh:mm |
| grouptype | 集計単位を選択します | 画面での該当項目：集計単位 1：月 2：日 3：時 4：分 5：曜日 |
No | query | integer |
3 ※1～5で指定ください。 |
| account_ids | エージェントを選択します | 画面での該当項目：エージェント | Yes | query | string | -- |
| phone_number_ids | 発信番号を選択します | 画面での該当項目：発信番号 | Yes | query | string | -- |
| Authorization | APIトークン認証方式の場合に用います | ''Tokenトークン文字列'と入力します | Yes | header | string | -- |
4.4 レスポンスコード
日時・曜日別レポート（エージェント別）のレスポンスコードは「2.4 レスポンスコード」と同様です。
4.5 ヘッダー
日時・曜日別レポート（エージェント別）のヘッダーは「2.5 ヘッダー」と同様です。
4.6 レスポンスボディ
日時・曜日別レポート（エージェント別）のレスポンスボディは以下となります。
● 取得に成功した場合の例
{
time: "00:00",
call_cnt: "0",
connected_cnt: "0",
abandon_cnt: "0",
connected_rate: "0",
talk_time_min: "0",
talk_time_avg: "0",
talk_time_max: "0",
talk_time_sum: "0",
wait_time_min: "0",
wait_time_avg: "0",
wait_time_max: "0",
wait_time_sum: "0"
}
● 取得に失敗した場合の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
4.7 レスポンスパラメータ
日時・曜日別レポート（エージェント別）のレスポンスパラメータは以下となります。
| time | 画面上での該当項目：日時／曜日 ・集計単位で月／日／時間／時間（10 分）を選択した場合は日時、曜日を選択した場合は曜日を表示します |
|---|---|
| call_cnt | 画面での該当項目：発信数 ・発信を開始した呼数です ・アウトバウンドイベントが発生（発信を開始）した日時で集計します |
| connected_cnt | 画面での該当項目：コンタクト数 ・ 発信先が応答した呼数です ・ アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| abandon_cnt | 画面での該当項目：未コンタクト数 ・発信先が電話に応答しなかった呼数です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| connected_rate | 画面での該当項目：コンタクト率(%) ・発信を開始した呼数の内、発信先が応答した呼数の割合を「コンタクト数÷発信数」で算出します |
| talk_time_min | 画面での該当項目：コンタクト通話集計・最小 ・発信が応答してから電話を切るまでの最小通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| talk_time_avg | 画面での該当項目：コンタクト通話集計・平均 ・発信が応答してから電話を切るまでの平均通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨てて表示します |
| talk_time_max | 画面での該当項目：コンタクト通話集計・最大 ・発信が応答してから電話を切るまでの最大通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| talk_time_sum | 画面での該当項目：コンタクト通話集計・合計 ・発信が応答してから電話を切るまでの合計通話時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| wait_time_min | 画面での該当項目：コンタクトまでの所要時間・最小 ・発信を開始してから発信先が応答するまでに要した最小時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| wait_time_avg | 画面での該当項目：コンタクトまでの所要時間・平均 ・発信を開始してから発信先が応答するまでに要した平均時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します ※小数点以下は切り捨して表示です |
| wait_time_max | 画面での該当項目：コンタクトまでの所要時間・最大 ・発信を開始してから発信先が応答するまでに要した最大時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
| wait_time_sum | 画面での該当項目：コンタクトまでの所要時間・合計 ・発信を開始してから発信先が応答するまでに要した合計時間です ・アウトバウンド切断イベントが発生（電話を切った）した日時で集計します |
4.8 エラー仕様
日時・曜日別レポート（エージェント別）のエラー仕様は以下となります。
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| from | 開始日時より前の終了日時を設定する | ValidateException | VALIDATE_ERROR | greater than to |
| 開始日時から終了日時までの範囲が2年より広い状態の場合 | 集計期間は2年(730日)以内で指定してください | |||
| to | 開始日時より前の終了日時を設定する | ValidateException | VALIDATE_ERROR | greater than to |
| 開始日時から終了日時までの範囲が2年より広い状態の場合 | 集計期間は2年(730日)以内で指定してください | |||
| grouptype | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 集計対象が範囲 「1:月」「2:日」「3:時」「4:分」「5:曜日」以外の場合 | 1〜5までにしてください | |||
| account_ids | 未入力 | ValidateException | VALIDATE_ERROR |
report_account_i_ds:値がありません |
| 半角数字以外を入力した場合 | 引数が数値でありません: '{入力文字列}' | |||
| アカウント一覧に存在しないアカウントIDを入力した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| phone_number_ids | 未入力 | ValidateException | VALIDATE_ERROR | report_dialed_number_i_ds:値がありません |
| 半角数字以外を入力した場合 | 引数が数値でありません: '{入力文字列}' | |||
| 電話番号一覧に存在しない電話番号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 | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
5.APIリクエスト数の消費仕様について
BIZTEL API（アウトバウンドレポート取得API）のライセンス消費数は以下となります。
| 認証方式 | ライセンス消費数 | 備考 |
|---|---|---|
| APIトークン認証方式 | １リクエストにつき、１消費 |
累積APIリクエスト数、累積APIレスポンスオブジェクト数ともに１づつ消費します。 |