| 目的 |
外部システムからBIZTEL APIを実行することにより、それぞれの履歴を取得したりBIZTEL APIの利用状況を取得することができます。 |
|---|---|
| 対象プラン |
|
| 用語 |
【BIZTEL API】 BIZTELとして公開しているAPIとなり、外部システムからBIZTELに対して実行処理や履歴などの取得を行うことができるパラメーターが用意されています。（履歴取得APIはBIZTEL APIの1つとなります。) |
| ポイント |
・本機能をご利用頂く場合、「履歴取得API」のオプション契約が必須です。 ※外部連携先の基本契約ライセンスの追加・変更等が必要な場合がございます。 ・BIZTEL APIの実行にはAPIリクエスト数の上限と、連続実行に関する制限があります。 (詳細はBIZTEL 管理画面 > システム設定 > ライセンス設定をご参照ください) ・月間のAPIリクエスト数、APIレスポンスオブジェクト数の上限は、各100,000件となります。 |
・本マニュアルはHTML/PHP(PCRE正規表現等)/WebAPIの基礎的な技術知識がある、WEB系開発者様やCRMベンダー様を対象にしております。
目次
※項目名をクリックいただく事で項目が展開され、参照したい手順へ移動できます。
1. 履歴取得API機能概要
外部システムからBIZTEL APIを実行することにより、BIZTELの情報取得が可能です。
| 項番 | 動線 |
|---|---|
| ① | HTTPリクエストにて、BIZTEL APIを実行します。 |
| ② | HTTPリクエストを受取、求められている情報をレスポンスします。 |
本マニュアルでは、それぞれのパラメータについて記載します。
●発着信履歴取得API
●コールセンター履歴取得API
●エージェント活動履歴取得API
●利用状況取得API
2. 発着信履歴取得API
本項では、発着信履歴取得APIのパラメータ等を記載します。
2.1 リクエスト方式
発着信履歴取得APIの認証方式は以下となります。
| 認証方式 |
HTTP |
URI |
備考 |
|---|---|---|---|
| APIトークン 認証方式 |
GET | /public/api/v1/call_log |
外部システムからBIZTEL APIを実行する仕組みになります。 APIトークンによるアカウント認証が必要となります。 詳細は「API認証トークン」を参照ください。 |
2.2 リクエストパラメータ
発着信履歴取得APIのリクエストパラメータは以下となります。
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| id | 発着信履歴IDを指定します | 管理画面での該当項目：なし | No | query | integer | Null |
| call_type | 検索種別を選択します | 管理画面での該当項目：検索種別 0：すべて 1：内線通話を検索 2：外線着信を検索 3：外線発信を検索 4：指定通知番号での外線着信 |
No | query | integer | 0 |
| anonymous | 検索結果に非通知を含めるかを指定します | 管理画面での該当項目：非通知を含める（チェックボックス） 検索種別で『3：外線からの端末着信』を選択した場合に選択します |
No | query | integer | Null |
| caller_id | 発信番号を指定します | 管理画面での該当項目：発信番号 | No | query | string | Null |
| caller_id_name | 通知番号を指定します | 管理画面での該当項目：なし | No | query | string | Null |
| called_id | 着信番号を指定します | 管理画面での該当項目：着信番号 | No | query | string | Null |
| answer_id | 最終着信番号を指定します | 管理画面での該当項目：なし | No | query | string | Null |
| from_bill_sec | 通話時間（開始）を指定します | 管理画面での該当項目：通話時間（開始） | No | query | string |
Null ※半角数字のみ |
| to_bill_sec | 通話時間（終了）を指定します | 管理画面での該当項目：通話時間（終了） | No | query | string |
Null ※半角数字のみ |
| exten_no | 内線番号を指定します | 管理画面での該当項目：なし | No | query | string | Null |
| request_id | リクエストIDを指定します | 管理画面での該当項目：リクエストID | No | query | string | Null |
| memo | メモを指定します | 管理画面での該当項目：メモ | No | query | string | Null |
| created_at_start | 履歴作成日時（開始）を指定します | 管理画面での該当項目：期間（開始） | No | query | date |
Null yyyy-mm-dd hh:mm:ss |
| created_at_end | 履歴作成日時（終了）を指定します | 管理画面での該当項目：期間（終了） | No | query | date |
Null yyyy-mm-dd hh:mm:ss |
| id_start | 履歴に付与されるユニークなIDの開始を指定します。 | 管理画面での該当項目：なし | No | query | integer |
Null 半角数字のみ |
| id_end | 履歴に付与されるユニークなIDの終了を指定します。 | 管理画面での該当項目：なし | No | query | integer |
Null 半角数字のみ |
| user_memo | 応対メモを指定します |
管理画面での該当項目：応対メモ ※BIZTELバージョン 3.8.0 以上で利用可能です。 |
No | query | string |
Null |
| Authorization | APIトークン認証方式の場合に用います | ''Token トークン文字列'と入力します | Yes | header | string | -- |
※1回のリクエストに対しての取得上限は1,000件となります。
※月間100,000件が上限となります。
※初期値が Nul lの場合、管理画面と同様に検索条件の指定なしとして扱われます。
● 実行形式（APIトークン認証方式）
macOSのターミナルにて下記コマンドを入力する場合の形式です。
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★契約BIZETLサーバFQDN★:8000/public/api/v1/call_log?★リクエストパラメータ★"
● 入力サンプル
発信内線 1801、着信番号 03XXXXXXXX のデータを取得する場合
curl -X GET --header "Accept: application/json" --header "Authorization: Token e512078873c3da913025f6b6424bd282ed65715878ea937dc1225623c1fc6c59ce0263524e4e34af" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/call_log?call_type=0&caller_id=1801&called_id=03xxxxxxxx"
2.3 レスポンス
2.3.1 レスポンスコード
API連携時のレスポンスコードは以下となります。
| HTTP Status Code | Reason | 説明 |
|---|---|---|
| 200 | Successful Operation | 成功 |
| 400 | Bad Request | 不正なリクエスト |
| 401 | Unauthorized | 認証失敗 |
| 429 | TooManyRequest | バースト上限の超過 |
| 500 | Internal Server Error | システム障害 |
2.3.2 ヘッダー
発着信履歴取得APIのヘッダー情報は以下となります。
| Response Headers |
|---|
| { "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": "*", "access-control-expose-headers": "Content-Disposition", "cache-control": "no-cache, private", "connection": "keep-alive", "content-encoding": "gzip", "content-type": "application/json", "date": "Mon, 20 Apr 2020 03:57:27 GMT", "referrer-policy": "same-origin", "server": "nginx", "strict-transport-security": "max-age=31536000; includeSubDomains", "transfer-encoding": "chunked", "vary": "Accept-Encoding", "x-account-id": "10012", "x-content-type-options": "nosniff", "x-frame-options": "SAMEORIGIN", "x-ratelimit-limit": "1", "x-ratelimit-remaining": "0", "x-robots-tag": "noindex", "x-xss-protection": "1; mode=block" }
|
2.3.3 ボディ
発着信履歴取得APIのレスポンスボディの例を記載します。
| 状況 |
Response Body |
|---|---|
| 履歴の取得に成功した場合 |
{ "user_memo":null, |
| 履歴の取得に失敗した場合 | { "name": "AuthenticationException", "type": "UNAUTHENTICATED", "exception_id": null, "message": "Unauthenticated: cause=unknown auth method.", "messages": null, "reason": "Unauthenticated: cause=unknown auth method." } |
2.3.4 レスポンスパラメータ
発着信履歴取得APIのレスポンスパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| id |
管理画面での該当項目：ID 履歴に付与される（10000番台の）IDです |
| answer_agent_id |
最終的に応答したエージェントのIDです （アカウントの一覧画面で確認可能な10000番台のID） ※コールセンター着信でない場合は、Nullとなります |
| answer_date |
着信に応答した日時です ※応答しなかった場合はNullとなります |
| answer_id | 管理画面での該当項目：最終着信番号 |
| answer_name | 管理画面での該当項目：最終着信者名 |
| bill_sec | 管理画面での該当項目：通話時間 |
| business_id |
管理画面上での該当項目：なし |
| business_name |
管理画面での該当項目：なし |
| call_date |
管理画面での該当項目：時刻 発着信が行われた日時です |
| callback |
管理画面での該当項目：コールバックフラグ コールバックAPIによる発信かどうかのフラグです |
| called_id | 管理画面での該当項目：着信番号 |
| called_id_name |
管理画面での該当項目：入力番号 発信元が入力した着信先の番号です |
| called_name |
管理画面での該当項目：着信者名 （電話端末名、着信グループ名、コールセンター業務名が表示されます。外線発信通話の場合はNullとなります） |
| caller_id | 管理画面での該当項目：発信番号 |
| caller_id_name |
管理画面での該当項目：通知番号 発信者が着信先に通知した番号です |
| caller_name |
管理画面での該当項目：発信者名 （外線着信通話の場合はNullとなります） |
| duration |
管理画面での該当項目：通話時間（応答までの時間を含む） 発着信の開始から通話終了までの時間（秒）です |
| monitor_logs |
管理画面での該当項目：録音 録音ファイルの有無を表します（０：録音ファイルなし／１：録音ファイルあり） |
| request_code | 管理画面での該当項目：リクエストコード |
| request_id | 管理画面での該当項目：リクエストID |
| user_memo | 管理画面での該当項目：応対メモ |
| memo | 管理画面での該当項目：履歴メモ |
2.3.5 エラー時のパラメータ
発着信履歴取得APIのエラー時のパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| name | 例外名 |
| type | 例外タイプ |
| exception_id | 例外ID |
| message | 例外メッセージ |
| messages | 例外trace |
| reason | 例外原因 |
2.4 エラー仕様
発着信履歴取得APIのエラー仕様は以下となります。
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| from_bill_sec | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 数字にしてください |
| to_bill_sec | 半角数字以外を入力した場合 | 数字にしてください | ||
| created_at_start | 半角数字、-（ハイフン）/（スラッシュ）:（コロン）以外を入力した場合 ※日付形式以外を入力した場合 |
正しい日付ではありません | ||
| created_at_end | 半角数字、-（ハイフン）/（スラッシュ）:（コロン）以外を入力した場合 ※日付形式以外を入力した場合 |
正しい日付ではありません | ||
| id_start | 半角数字以外を入力した場合 | 数字にしてください | ||
| id_end | 半角数字以外を入力した場合 | 数字にしてください | ||
| Authorization | 未入力 | AuthorizationException | FORBIDDEN | This action is unauthorized |
| 認証に失敗した場合 ※「Token」のみ入力した場合 |
AuthenticationException | UNAUTHENTICATED | Unauthenticated: method=personal_token, cause=invalid request | |
| 認証に失敗した場合 ※「Token {誤ったToken文字列}」を入力した場合 |
Unauthenticated: method=personal_token, cause=invalid token. | |||
| -- | 履歴取得APIライセンスがOFFの状態で発着信履歴取得APIを実行した場合 | AuthenticationException | FORBIDDEN | This action is unauthorized. |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
3. コールセンター履歴取得API
本項では、コールセンター履歴取得APIのパラメータ等を記載します。
3.1 リクエスト方式
コールセンター履歴取得APIの認証方式は以下となります。
| 認証方式 |
HTTP |
URI |
備考 |
|---|---|---|---|
| APIトークン 認証方式 |
GET | /public/api/v1/queue_log |
外部システムからBIZTEL APIを実行する仕組みになります。 APIトークンによるアカウント認証が必要となります。 |
3.2 リクエストパラメータ
コールセンター履歴取得APIのリクエストパラメータは以下となります。
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| account_id | アカウントに付与されるユニークなIDを指定します | 管理画面での該当項目：なし | No | query | integer | Null |
| queue_id | コールセンターに付与されるユニークなIDを指定します | 管理画面での該当項目：なし | No | query | integer | Null |
| business_id | 業務ラベルに付与されるユニークなIDを指定する | 管理画面での該当項目：なし | No | query | integer | Null |
| caller_id | 発信番号を指定します | 管理画面での該当項目：発信番号 | No | query | string | Null |
| called_id | 着信番号を指定します | 管理画面での該当項目：着信番号 | No | query | string | Null |
| event | イベントを指定します 指定可能なイベントは「3.4 イベント」を参照ください。 |
管理画面での該当項目：イベント | No | query | string | Null |
| from_hold_time | 待ち時間（開始）を指定します | 管理画面での該当項目：待ち時間（開始） | No | query | string |
Null ※半角数字のみ |
| to_hold_time | 待ち時間（終了）を指定します | 管理画面での該当項目：待ち時間（終了） | No | query | string |
Null ※半角数字のみ |
| from_call_time | 通話時間（開始）を指定します | 管理画面での該当項目：通話時間（開始） | No | query | string |
Null ※半角数字のみ |
| to_call_time | 通話時間（終了）を指定します | 管理画面での該当項目：通話時間（終了） | No | query | string |
Null ※半角数字のみ |
| from_origposition | 待ちポジション（開始）を指定します | 管理画面での該当項目：待ちポジション | No | query | string |
Null ※半角数字のみ |
| to_origposition | 待ちポジション（終了）を指定します | 管理画面での該当項目：待ちポジション | No | query | string |
Null ※半角数字のみ |
| request_id | リクエストIDを指定します | 管理画面での該当項目：リクエストID | No | query | string | Null |
| created_at_start | 期間を指定します | 管理画面での該当項目：なし | No | query | date |
Null yyyy-mm-dd hh:mm:ss |
| created_at_end | 期間を指定します | 管理画面での該当項目：なし | No | query | date |
Null yyyy-mm-dd hh:mm:ss |
| from_start_date | 期間を指定します | 管理画面での該当項目：『期間（通話開始時刻）』の開始 | No | query | date |
Null yyyy-mm-dd hh:mm:ss |
| to_start_date | 期間を指定します | 管理画面での該当項目：『期間（通話開始時刻）』の終了 | No | query | date |
Null yyyy-mm-dd hh:mm:ss |
| id_start | 履歴に付与されるユニークなIDの開始を指定します。 | 管理画面での該当項目：なし | No | query | integer | Null |
| id_end | 履歴に付与されるユニークなIDの終了を指定します。 | 管理画面での該当項目：なし | No | query | integer | Null |
| user_memo | 応対メモを指定します |
管理画面での該当項目：応対メモ ※BIZTELバージョン 3.8.0 以降で利用可能です。 |
No | query | string | Null |
| Authorization | APIトークン認証方式の場合に用います | 'Token トークン文字列'と入力します | Yes | header | string | -- |
※1回のリクエストに対しての取得上限は1,000件となります。
※Nullの場合、管理画面と同様に検索条件の指定なしとなります。
● 実行形式（APIトークン認証方式）
macOSのターミナルにて下記コマンドを入力する場合の形式です。
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★ご契約BIZTELサーバFQDN★:8000/public/api/v1/queue_log?★リクエストパラメータ★"
● 入力サンプル
コールセンター内線 7800 のリクエストID 20042100001268090005 を取得する例
curl -X GET --header "Accept: application/json" --header "Authorization: Token d3a8cfde20921ee480431e40c7e6736304b5aec9784a0a4bba26cc52b03c65c9cee583964284b846" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/queue_log?called_id=7800&request_id=20042100001268090005"
3.3 レスポンス
3.3.1 レスポンスコード
API連携時のレスポンスコードは以下となります。
| HTTP Status Code | Reason | 説明 |
|---|---|---|
| 200 | Successful Operation | 成功 |
| 400 | Bad Request | 不正なリクエスト |
| 401 | Unauthorized | 認証失敗 |
| 429 | TooManyRequest | バースト上限の超過 |
| 500 | Internal Server Error | システム障害 |
3.3.2 ヘッダー
コールセンター履歴取得APIのヘッダー情報は以下となります。
| Response Headers |
|---|
| { "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": "*", "access-control-expose-headers": "Content-Disposition", "cache-control": "no-cache, private", "connection": "keep-alive", "content-encoding": "gzip", "content-type": "application/json", "date": "Tue, 21 Apr 2020 09:03:38 GMT", "referrer-policy": "same-origin", "server": "nginx", "strict-transport-security": "max-age=31536000; includeSubDomains", "transfer-encoding": "chunked", "vary": "Accept-Encoding", "x-account-id": "10012", "x-content-type-options": "nosniff", "x-frame-options": "SAMEORIGIN", "x-ratelimit-limit": "1", "x-ratelimit-remaining": "0", "x-robots-tag": "noindex", "x-xss-protection": "1; mode=block" } |
3.3.3 ボディ
コールセンター履歴取得APIのレスポンスボディの例を記載します。
| 状況 |
Response Body |
|---|---|
| 履歴の取得に成功した場合 ※イベントを応答とした場合の例 |
{ "id": 10024, "account_id": "10016", "account_kana": "kanatsu_user1", "account_name": "kn_user1", "business_id": 10001, "business_name": "ｘｘコールセンター", "call_time": null, "called_id": "7800", "caller_id": "1801", "event": "CONNECT", "hold_time": 3, "monitor_logs": 1, "origposition": null, "queue_exten": "7800", "queue_id": "10004", "queue_name": "kanatsu_Callcenter1", "request_id": "20051200003268090005", "start_time": "2020-05-12 18:59:27", "time": "2020-05-12 18:59:36" }, |
| 履歴の取得に失敗した場合 | { "name": "ValidateException", "type": "VALIDATE_ERROR", "exception_id": null, "message": "数字にしてください", "messages": { "holdtime": "数字にしてください" }, "reason": null } |
3.3.4 レスポンスパラメータ
コールセンター履歴取得APIのレスポンスパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| id | 管理画面上での該当項目：ID |
| account_id | 管理画面上での該当項目：アカウントID |
| account_kana | 管理画面上での該当項目：名前 |
| account_name | 管理画面での該当項目：アカウント |
| business_id |
管理画面上での該当項目：なし ※BIZTELバージョン 3.7.20 未満は空欄で出力されます。 |
| business_name |
管理画面上での該当項目：業務ラベル名 ※BIZTELバージョン 3.7.20 未満は「他業務」と出力されます。 |
| call_time |
管理画面での該当項目：通話時間 ※COMPLETEUNKNOWNはBIZTELバージョン 3.7.0 以降で利用可能です。 |
| called_id | 管理画面上での該当項目：着信番号 |
| caller_id | 管理画面上での該当項目：発信番号 |
| event | 管理画面上での該当項目：イベント ※イベント詳細は「3.4 イベント」を参照ください。 |
| hold_time |
管理画面上での該当項目：待ち時間 ※CONECT（応答）イベント以後に記録されます |
| monitor_logs |
管理画面での該当項目：録音 録音ファイルの有無を表します（０：録音ファイルなし／１：録音ファイルあり） |
| origposition |
管理画面上での該当項目：待ちポジション 着信時のキュー内での順位です |
| queue_exten | 管理画面上での該当項目：コールセンター内線番号 |
| queue_id |
コールセンター業務のユニークIDです。 ※管理画面上での該当項目：なし（コールセンター業務の一覧画面にて『IDカラム』が該当します） |
| queue_name | 管理画面上での該当項目：コールセンター業務名 |
| request_id | 管理画面上での該当項目：リクエストID |
| start_time | 管理画面上での該当項目：通話開始時刻 |
| time | 管理画面での該当項目：イベント時刻 （詳細画面でのみ表示） |
| user_memo | 管理画面での該当項目：応対メモ |
3.3.5 エラー時のパラメータ
コールセンター履歴取得APIのエラー時のパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| name | 例外名 |
| type | 例外タイプ |
| exception_id | 例外ID |
| message | 例外メッセージ |
| messages | 例外trace |
| reason | 例外原因 |
3.4 イベント
コールセンター履歴のイベントの詳細は以下となります。
| イベント名 | 詳細 | 履歴表示タイミング |
|---|---|---|
| GUIDANCE | 初期ガイダンス開始 | 初期ガイダンスの再生が開始したタイミング |
| GUIDANCE-COMPLETE | 初期ガイダンス終了 | 初期ガイダンスの再生が終了したタイミング |
| GUIDANCE-ABANDON | 初期ガイダンス中の切断 | 初期ガイダンス再生中にお客様にて切断したタイミング |
| ENTERQUEUE | キュー | 初期ガイダンスが終了し、キューに入ったタイミング |
| CALLAGENT | 呼び出し | エージェントを呼び出し始めたタイミング |
| CONNECT | 応答 |
エージェントが応答したタイミング （エージェント向けガイダンス終了後） |
| RINGNOANSWER | 応答不能 | ACDで設定されたタイムアウト秒数を経過したタイミング |
| EXITWITHTIMEOUT | 応答不能時ルール | 着信設定 > 不在着信時ルールで設定された秒数を経過したタイミング |
| EXITWITHKEY | 待ち呼離脱 | エージェントが応答する前にお客様にて「＃」のダイヤル操作をしたタイミング |
| ABANDON | 放棄呼 | エージェントが応答する前にお客様にて切断したタイミング |
| AGENTDUMP | エージェント向けガイダンス中の切断 | エージェント向けガイダンス再生中にエージェントにて切断したタイミング |
| MOH_START | 保留開始 | エージェントにて保留を開始したタイミング |
| MOH_STOP | 保留終了 | エージェントにて保留を終了したタイミング |
| COMPLEATECALLER | 切断（お客様） | お客様から通話を切断したタイミング |
| COMPLEATEAGENT | 切断（エージェント） | エージェントから通話を切断したタイミング |
| COMPLETEUNKNOWN | 切断（不明） | お客様とエージェントのどちらが通話を切断したか判断できないもの ※ネットワーク異常等、何らかの要因で通話が切断されたタイミング |
| OUTBOUND | アウトバウンド | エージェントが外線に発信したタイミング |
| OUTBOUND-COMPLETE | アウトバウンド切断 | 外線発信通話が終了したタイミング |
| OUTBOUND-CONNECT | アウトバウンド応答 |
発信先の外線が応答したタイミング |
3.5 エラー仕様
コールセンター履歴取得APIのエラー仕様は以下となります。
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| from_hold_time | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 数字にしてください |
| to_hold_time | ||||
| from_call_time | ||||
| to_call_time | ||||
| from_origposition | ||||
| to_origposition | ||||
| created_at_start | 半角数字、-（ハイフン）/（スラッシュ）:（コロン）以外を入力した場合 ※日付形式以外を入力した場合 |
正しい日付ではありません | ||
| created_at_end | ||||
| from_start_date | ||||
| to_start_date | ||||
| id_start | 半角数字以外を入力した場合 | 数字にしてください | ||
| id_end | ||||
| Authorization | 未入力 | AuthorizationException | FORBIDDEN | This action is unauthorized |
| 認証に失敗した場合 ※「Token」のみ入力した場合 |
AuthenticationException | UNAUTHENTICATED | Unauthenticated: method=personal_token, cause=invalid request | |
| 認証に失敗した場合 ※「Token {誤ったToken文字列}」を入力した場合 |
Unauthenticated: method=personal_token, cause=invalid token. | |||
| -- | 履歴取得APIライセンスがOFFの状態で発着信履歴取得APIを実行した場合 | AuthenticationException | FORBIDDEN | This action is unauthorized. |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
4. エージェント活動履歴取得API
4.1 リクエスト方式
エージェント活動履歴取得APIの認証方式は以下となります。
| 認証方式 |
HTTP |
URI |
備考 |
|---|---|---|---|
| APIトークン 認証方式 |
GET | 'public/api/v1/account_status_call_log |
外部システムからBIZTEL APIを実行する仕組みになります。 APIトークンによるアカウント認証が必要となります。 詳細は「API認証トークン」を参照ください。 |
4.2 リクエストパラメータ
エージェント活動履歴取得APIのリクエストパラメータは以下となります。
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| id | エージェント活動履歴のIDを指定します | 管理画面での該当項目：エージェント活動履歴 > 一覧画面 > IDカラムが該当します | No | query | integer | Null |
| account_id | アカウントに付与されるユニークなIDを指定します | 管理画面での該当項目：アカウント > 一覧画面 > IDカラムが該当します | No | query | integer | Null |
| account_name | アカウントを指定します | 管理画面での該当項目：アカウント | No | query | string | Null |
| callback_number | アカウントのサインイン端末を指定します | 管理画面での該当項目：サインイン端末 | No | query | string | Null |
| dst_account_name | 通話相手の名称を指定します | 管理画面での該当項目：なし | No | query | string | Null |
| dst_callback_number | 通話相手の電話番号を指定します | 管理画面での該当項目：なし | No | query | string | Null |
| status_id | ステータスのIDを指定します | 管理画面での該当項目：ステータス > 一覧画面 > IDカラムが該当します | No | query | integer | Null |
| queue_id | エージェントが対応したコールセンターのIDを指定します | 管理画面での該当項目：コールセンター > 一覧画面 > IDカラムが該当します | No | query | integer | Null |
| queue_name | エージェントが対応したコールセンター業務の名称を指定します | 管理画面での該当項目：コールセンター名 | No | query | string | Null |
| business_id | 業務ラベルのIDを指定します | 管理画面での該当項目：業務ラベル > 一覧画面 > IDカラムが該当します | No | query | integer | Null |
| created_at_start | 履歴の作成日時（開始）を指定します | 管理画面での該当項目：期間（開始） | No | query | string |
Null ※yyyy-mm-dd hh:mm:ss |
| created_at_end | 履歴の作成日時（終了）を指定します | 管理画面での該当項目：期間（終了） | No | query | string |
Null ※yyyy-mm-dd hh:mm:ss |
| request_id | リクエストIDを指定します | 管理画面での該当項目：リクエストIDカラムが該当します | No | query | string | Null |
| id_start | 履歴に付与されるユニークなIDの開始を指定します | 管理画面での該当項目：なし | No | query | integer |
Null ※半角数字のみ |
| id_end | 履歴に付与されるユニークなIDの終了を指定します | 管理画面での該当項目：なし | No | query | integer |
Null ※半角数字のみ |
| from_diff_seconds | ステータス経過時間（開始）を指定します | 管理画面での該当項目：経過時間(秒)（開始） | No | query | integer |
Null ※半角数字のみ |
| to_diff_seconds | ステータス経過時間（終了）を指定します | 管理画面での該当項目：経過時間(秒)（終了） | No | query | integer |
Null ※半角数字のみ |
| Authorization | APIトークン認証方式の場合に用います | 'Token トークン文字列'と入力します | Yes | header | string | -- |
※1回のリクエストに対しての取得上限はBIZTELバージョンにより異なります。
BIZTELバージョン 3.7.X まで：1,000件 / 1回
BIZTELバージョン 3.8.0 以降：10,000件 / 1回
※Nullの場合、管理画面と同様に検索条件の指定なしとなります。
● 実行形式（APIトークン認証方式）
macOSのターミナルにて下記コマンドを入力する場合の形式です。
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★ご契約BIZTELサーバFQDN★:8000/public/api/v1/account_status_call_log?★リクエストパラメータ★"
● 入力サンプル
サインイン端末が 1800 のデータを取得する場合
curl -X GET --header "Accept: application/json" --header "Authorization: Token d3a8cfde20921ee480431e40c7e6736304b5aec9784a0a4bba26cc52b03c65c9cee583964284b846" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/account_status_call_log?callback_number=1800"
4.3 レスポンス
4.3.1 レスポンスコード
エージェント活動履歴取得APIのAPI連携時のレスポンスコードは以下となります。
| HTTP Status Code | Reason | 説明 |
|---|---|---|
| 200 | Successful Operation | 成功 |
| 400 | Bad Request | 不正なリクエスト |
| 401 | Unauthorized | 認証失敗 |
| 429 | TooManyRequest | バースト上限の超過 |
| 500 | Internal Server Error | システム障害 |
4.3.2 ヘッダー
エージェント活動履歴取得APIのヘッダー情報は以下となります。
| Response Headers |
|---|
| { "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": "*", "access-control-expose-headers": "Content-Disposition", "cache-control": "no-cache, private", "connection": "keep-alive", "content-encoding": "gzip", "content-type": "application/json", "date": "Tue, 21 Apr 2020 10:01:01 GMT", "referrer-policy": "same-origin", "server": "nginx", "strict-transport-security": "max-age=31536000; includeSubDomains", "transfer-encoding": "chunked", "vary": "Accept-Encoding", "x-account-id": "10012", "x-content-type-options": "nosniff", "x-frame-options": "SAMEORIGIN", "x-ratelimit-limit": "1", "x-ratelimit-remaining": "0", "x-robots-tag": "noindex", "x-xss-protection": "1; mode=block" } |
4.3.3 ボディ
エージェント活動履歴取得APIのレスポンスボディの例を記載します。
| 状況 |
Response Body |
|---|---|
| 履歴の取得に成功した場合 ※イベントを応答とした場合の例 |
{ "id": 10086, "account_id": 10016, "account_kana": "kanatsu_user1", "account_name": "kn_user1", "business_id": 10001, "business_name": "ｘｘコールセンター", "callback_number": "1800", "diff_seconds": 2, "dst_account_id": null, "dst_account_kana": null, "dst_account_name": null, "dst_callback_number": "070XXXXXXXX", "queue_id": 10004, "queue_name": "kanatsu_Callcenter1", "request_id": "20042100001668090005", "status_id": 20, "status_name": "通話中", "created_at": "2020-04-21 17:22:00", "updated_at": "2020-04-21 17:22:02" } |
| 履歴の取得に失敗した場合 | { "name": "ValidateException", "type": "VALIDATE_ERROR", "exception_id": null, "message": "正しい日付ではありません", "messages": { "created_at": "正しい日付ではありません" }, "reason": null } |
4.3.4 レスポンスパラメータ
エージェント活動履歴取得APIのレスポンスパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| id | 管理画面上での該当項目：ID |
| account_id | 管理画面上での該当項目：アカウントID |
| account_kana | 管理画面上での該当項目：名前 |
| account_name | 管理画面での該当項目：アカウント |
| business_id |
管理画面上での該当項目：なし |
| business_name | 管理画面上での該当項目：業務ラベル名 |
| callback_number | 管理画面での該当項目：サインイン端末 |
| diff_seconds | 管理画面での該当項目：経過時間（秒） |
| dst_account_id | 管理画面での該当項目：なし ※通話相手先エージェントのID ※未使用のパラメータですが、表示されます。 |
| dst_account_kana | 管理画面での該当項目：なし ※通話相手先エージェントの名前 ※未使用のパラメータですが、表示されます。 |
| dst_account_name | 管理画面での該当項目：なし ※通話相手先エージェントのアカウント ※未使用のパラメータですが、表示されます。 |
| dst_callback_number | 管理画面での該当項目：なし ※通話相手先エージェントのサインイン端末 ※未使用のパラメータですが、表示されます。 |
| queue_id |
管理画面での該当項目：なし ※エージェントが対応したコールセンター業務のID（コールセンター業務 > 一覧画面 > IDカラム） |
| queue_name | 管理画面での該当項目：コールセンター業務名 |
| request_id | 管理画面での該当項目：リクエストID |
| status_id |
管理画面での該当項目：なし ※ステータス > 一覧画面 > IDカラム |
| status_name | 管理画面での該当項目：ステータス |
| created_at | 管理画面での該当項目：時刻 |
| updated_at |
管理画面での該当項目：なし ※ステータス変更により、経過時間（diff_seconds）が更新された際に当該パラメータも更新されます |
4.3.5 エラー時のパラメータ
エラー時のパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| name | 例外名 |
| type | 例外タイプ |
| exception_id | 例外ID |
| message | 例外メッセージ |
| messages | 例外trace |
| reason | 例外原因 |
4.4 エラー仕様
エージェント活動履歴取得APIのエラー仕様は以下となります。
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| created_at_start | 半角数字、-（ハイフン）/（スラッシュ）:（コロン）以外を入力した場合 ※日付形式以外 | ValidateException | VALIDATE_ERROR | 正しい日付ではありません |
| created_at_end | ||||
| id_start | 半角数字以外を入力した場合 | 数字にしてください | ||
| id_end | ||||
| Authorization | 未入力 | AuthorizationException | FORBIDDEN | This action is unauthorized |
| 認証に失敗した場合 ※「Token」のみ入力した場合 |
AuthenticationException | UNAUTHENTICATED | Unauthenticated: method=personal_token, cause=invalid request | |
| 認証に失敗した場合 ※「Token {誤ったToken文字列}」を入力した場合 |
Unauthenticated: method=personal_token, cause=invalid token. | |||
| -- | 履歴取得APIライセンスがOFFの状態でエージェント活動履歴取得APIを実行する | FORBIDDEN | This action is unauthorized. | |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
5. 利用状況取得API
BIZTELにて利用するAPIの利用状況と利用上限を出力します。
●出力できる内容
月間のリクエスト数の累積地
月間のレスポンス数の累積地
月間のリクエスト数の上限値
月間のレスポンス数の上限値
●対象のBIZTEL API
コールバックAPI
履歴取得API（コールセンター履歴、発着信履歴、エージェント活動履歴）
5.1 リクエスト方式
利用状況取得APIの認証方式は以下となります。
| 認証方式 |
HTTP |
URI |
備考 |
|---|---|---|---|
| APIトークン 認証方式 |
GET | /public/api/v1/count |
APIトークンによるアカウント認証が必要となります。 |
5.2 リクエストパラメータ
利用状況取得APIのリクエストパラメータは以下となります。
|
パラメータ |
説明 |
URI |
備考 |
|---|---|---|---|
| Authorization | APIトークン認証方式の場合に用います | /public/api/v1/count | Token（トークン文字列）と入力します |
● 実行形式（APIトークン認証方式）
macOSのターミナルにて下記コマンドを入力する場合の形式です。
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★ご契約BIZTELサーバFQDN★:8000/public/api/v1/count"
● 入力サンプル
curl -X GET --header "Accept: application/json" --header "Authorization: Token 2d40d7e8a96ae226860efccde47d949240f0ce50fed4ba3871fe7fca7379e68c5673ccf58ed05a76" "https://sxxxxxxxxxxxx.u.biztel.jp:8000/public/api/v1/count"
5.3 レスポンス
5.3.1 レスポンスコード
API連携時のレスポンスコードは以下となります。
| HTTP Status Code | Reason | 説明 |
|---|---|---|
| 200 | Successful Operation | 成功 |
| 401 | Unauthorized | 認証失敗 |
| 500 | Internal Server Error | システム障害 |
5.3.2 ヘッダー
ヘッダー情報は以下となります。
| Response Headers |
|---|
| { "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":"*" "access-control-expose-headers":"Content-Disposition" "cache-control":"no-cache, private" "connection":"keep-alive" "content-encoding":"gzip" "content-type":"application/json" "date":"Wed, 13 May 2020 06:20:44 GMT" "referrer-policy":"same-origin" "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":"SAMEORIGIN" "x-robots-tag":"noindex" "x-xss-protection":"1; mode=block" } |
5.3.3 ボディ
レスポンスボディの例を記載します。
| 状況 |
Response Body |
|---|---|
| 履歴の取得に成功した場合 ※イベントを応答とした場合の例 |
{ "api_request_count": 4, "api_response_object_count": 4, "api_request_limit": 100000, "api_response_object_limit": 100000, } |
| 履歴の取得に失敗した場合 | { "name": "InvalidCodeException", "type": "NO_WAY", "exception_id": "c2d2c846af4a43a52330f1c09614ba70", "message": "NO_WAY", "messages": [], "reason": null } |
5.3.4 レスポンスパラメータ
レスポンスパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| api_request_count |
月間のリクエスト数の累積値です。 コールバックAPIまたは履歴取得API実行時、1回のリクエストにつき1加算されます。 ※累積値は毎月1日の00:00:00にリセットされます ※利用状況取得APIを実行した場合についても1加算されます ただし、利用状況取得APIを実行した直後は1つ前のレスポンス数が表示されます （BIZTEL管理画面の履歴メニューにて、検索ボタンをクリックして履歴を取得する場合は『api_request_count』『api_response_object_count』には加算されません） |
| api_response_object_count |
月間のレスポンス数の累積値です。 コールバックAPIまたは履歴取得API実行時、1回のレスポンスにつき1加算されます。 ※累積値は毎月1日の00:00:00にリセットされます。 ※利用状況取得APIを実行した場合についても1加算されます ただし、利用状況取得APIを実行した直後は1つ前のレスポンス数が表示されます （BIZTEL管理画面の履歴メニューにて、検索ボタンをクリックして履歴を取得する場合は『api_request_count』『api_response_object_count』には加算されません） |
| api_request_limit | リクエスト数の上限値です。 |
| api_response_object_limit | リクエスト数の上限値です。 |
5.3.5 エラー時のパラメータ
エラー時のパラメータは以下となります。
| パラメータ |
説明 |
|---|---|
| name | 例外名 |
| type | 例外タイプ |
| exception_id | 例外ID |
| message | 例外メッセージ |
| messages | 例外trace |
| reason | 例外原因 |
5.4 エラー仕様
エラー仕様は以下となります。
| パラメータ | エラー条件 | name | type | messages |
|---|---|---|---|---|
|
Authorization |
認証に失敗した場合 ※「Token」のみ入力した場合 |
AuthenticationException | UNAUTHENTICATED | Unauthenticated: method=personal_token, cause=invalid request |
| 認証に失敗した場合 ※「Token {誤ったToken文字列}」を入力した場合 |
AuthenticationException | UNAUTHENTICATED | Unauthenticated: method=personal_token, cause=invalid token. | |
| - | 履歴取得API、コールバックAPI、録音ファイル取得APIが共にライセンスがOFFの状態で利用状況取得APIを実行する | AuthenticationException | UNAUTHENTICATED | Unauthenticated: method=personal_token, cause=api license disabled |
5.5 注意事項
利用状況取得API実行時の返却値・累積値について
利用状況取得APIを実行した際の「api_request_count」「api_response_object_count」の返却値について、利用状況取得APIを実行した場合も、リクエスト数・レスポンス数をそれぞれ１消費します。
ただし、利用状況取得APIを実行して返却される値は「利用状況取得APIを実行する直前」のリクエスト数・レスポンス数の累積値となります。
例）現在のリクエスト数・レスポンス数の累積値がそれぞれ「０」である場合
■利用状況取得API実行：1回目
レスポンス内容
api_request_count = 0
api_response_object_count = 0
利用状況取得APIを実行する直前の累積値「０」となる
■利用状況取得API実行：2回目（※この間、他のAPIを一切実行していないものとする）
・レスポンス内容
api_request_count = 1
api_response_object_count = 1
「利用状況取得API実行：1回目」のカウントが追加された状態となる
※これによりAPIの利用回数がまだ残っているように見えても、実際は利用状況取得APIの実行により
上限に到達している場合が起こり得るため注意が必要です。
例）以下の前提でAPIを実行した場合
前提１）API利用上限：リクエスト数・レスポンス数それぞれ10回
前提２）現在の利用数：リクエスト数・レスポンス数それぞれ9回
・レスポンス内容
api_request_count = 9
api_response_object_count = 9
上記例の場合、一見すると後1回APIを実行できるように見えますが、この時点で既に利用状況取得APIに
よる利用回数の加算にて、上限に到達しているため以後は利用回数オーバーでAPI実行が制限されます。
IPアクセス制御について
IPアクセス制御を有効にしている場合、利用状況取得APIを実行する拠点(またはサーバ)のIPアドレスが登録されていないと通信がブロックされるため、事前に対象のIPアドレスをIPアクセス制御に設定してください。
6. パラメータコピー用ファイル
各履歴取得APIのパラメータは以下のファイルをダウンロード頂きご活用ください。