| 目的 |
外部システムからBIZTELに対してコマンドを送信することで、エージェントステータスの参照・更新が可能です。 |
|---|---|
| 対象プラン |
|
| 用語 |
【WebAPI】 汎用的なWeb技術を利用し、インターネットを介して外部システムとの連携を容易にする仕組みです。 【BIZTEL API】 BIZTELが公開するAPIを示します。 |
| ポイント |
・本機能は、BIZTELバージョン 3.8.0 以降で利用可能です。 ・本機能をご利用いただく場合、「エージェントステータス更新API」のライセンス契約が必要です。 |
・本マニュアルはHTML/PHP(PCRE正規表現等)/WebAPIの基礎的な技術知識がある、WEB系開発者様やCRMベンダー様を対象にしております。
目次
1.エージェントステータス更新APIの基本機能
エージェントステータス更新APIは、外部システムからBIZTELのエージェントステータスを参照・更新を可能とするAPIです。
動作イメージ図
| ①ステータス更新コマンドの送信 |
外部システムからBIZTELサーバに対して、エージェントステータス更新のリクエストを送信します。 |
|---|---|
| ②ステータス更新 | 外部システムから送信されたリクエストに従い、コマンド内で指定されたアカウントのステータスを更新します。 |
| ③実行結果を返却 | BIZTELは要求されたリクエストに沿ってエージェントステータスを更新し、結果を外部システムに返却します。 |
※ステータス更新APIは通話中のエージェントに対して実行するとエラーとなりますのでご注意ください。
2.エージェントステータス更新APIについて
2.1 API基本仕様
URI schemeは以下となります。
| Host | sXXXXXXXXXXXX.u.biztel.jp:8000 | BIZTELサーバアドレスとして指定されたFQDN |
|---|---|---|
| scheme | HTTPS | - |
2.2 リクエスト方式
エージェントステータス更新APIを実行する際のリクエスト方式は以下となります。
| 認証方式 | HTTPメソッド | URI | 備考 |
|---|---|---|---|
| APIトークン認証方式 | PUT | /public/api/v1/account/{id}/status |
APIトークンによるアカウント認証が必要です。 リクエストヘッダにAuthorization: Token (APIトークン)を指定します。 ※アカウント>APIトークンタブから払い出します。詳細は「1.APIトークン」を参照ください。 ※{id}= ステータスを更新するアカウントのIDです。 |
{ID}の確認方法
各メニューのIDは、BIZTEL管理画面のハンバーガーメニューから非表示となっているIDの項目にチェックを入れ、ご確認ください。
例）以下はアカウントの画面でIDを表示した例です。
2.3 リクエストパラメータ
エージェントステータス更新APIのリクエストパラメータは以下となります。
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| Authorization | API実行のためのトークンを指定する | 'Token トークン文字列'と入力 | Yes | header | string | -- |
| id | アカウントIDを指定します |
必須項目です。 画面での該当項目：アカウントID |
Yes | path | integer | -- |
| account_status_id | アカウントステイタスIDを指定します | No | query | integer | -- | |
| callback_extension_id | コールバック先内線IDを指定します | No | query | integer | -- | |
| callback_phone_number | コールバック先外線電話番号を選択します | No | query | string | -- |
実行例
● 実行形式
macOSのコンソールで実行する場合の例です。
curl -X PUT --header "Accept: application/json" --header "Authorization: Token ★払い出しトークン★" "https://★契約BIZETLサーバFQDN★:8000/public/api/v1/account/★アカウントID★/status?★リクエストパラメータ★"
● 入力サンプル
例）アカウントID：10001 のステータスを 受付可（account_status_id=9） に変更する。
curl -X PUT --header "Accept: application/json" --header "Authorization: Token f165c85da8387829aa27b57a1b8b37d9bd1aab86762ff6cb94dc812790a3b50b3f8c6f21dc051c89" "https://sXXXXXXXXXXXX.u.biztel.jp:8000/public/api/v1/account/10001/status?account_status_id=9"
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,no-store,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: Fri,26 May 2023 07:46:10 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: 10
x-ratelimit-remaining: 9
x-robots-tag: noindex
x-xss-protection: 1; mode=block
}
2.6 レスポンスボディ
エージェントステータス更新APIのレスポンスボディは以下となります。
● 更新成功時の例
{
"id": 10001,
"account_status_id": 9,
"account_status_name": "受付可",
"call_status_id": null,
"call_status_name": null,
"callback_extension_id": null,
"callback_extension_number": null,
"callback_phone_number": "012345678",
"created_at": "2023-05-19 00:00:00",
"updated_at": "2023-05-26 15:57:55",
"version": 1685084275
}
● 更新失敗時の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
2.7 レスポンスパラメータ
| id |
更新したアカウントのIDです。 |
|---|---|
| account_status_id |
アカウントの現在のステータスIDを表示します。 ※お客様にて追加したステータスを取得する場合、そのIDが表示されます。 |
| account_status_name | アカウントの現在のステータスの名前を表示します。 |
| call_status_id |
アカウントの現在の通話ステータスIDです。 |
| call_status_name | アカウントの現在の通話ステータスの名前を表示します。 |
| callback_extension_id | アカウントのサインイン端末のIDを表示します。 |
| call_status_name | アカウントのサインイン端末の内線番号を表示します。 |
| callback_phone_number | アカウントのサインイン端末の外線番号（ダイヤルイン番号）を表示します。 |
| updated_at | アカウント情報が更新された日時を表示します。 |
| created_at | アカウント情報が作成された日時を表示します。 |
| version | 楽観ロックの為のバージョンです。 |
2.8 エラー仕様
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| id | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「1〜9223372036854775806」以外を入力した場合 | 1〜9223372036854775806までにしてください | |||
| 存在しないアカウントIDを指定した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| account_status_id | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | account_status_id:引数が数値でありません: '{入力文字列}' |
| 「1〜9223372036854775806」以外を入力した場合 | account_status_id:1〜9223372036854775806までにしてください | |||
| 通話中のアカウントのステイタスを更新した場合 | AccountStatusChangeException | CANNOT_CHANGE_STATUS_CAUSE_NOW_CALLING | ステータスの変更に失敗しました 通話中または着信中の可能性があります 時間を置いて再度変更してください | |
| アカウントステイタスIDを更新する際にコールバック先内線IDがNULLの状態で内線IDを指定せずに更新した場合 | AccountCallbackChangeException | CANNOT_CHANGE_CALLBACK_NULL_CAUSE_NOW_LOGON | エージェントとしてサインインする場合、必ずサインイン端末を指定してください | |
| 存在しないステイタスIDを指定した場合 | EntityNotFoundException | NOT_FOUND | 対象が存在しません | |
| callback_extension_id | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | callback_extension_id:引数が数値でありません: '{入力文字列}' |
| 「1〜9223372036854775806」以外を入力した場合 | callback_extension_id:1〜9223372036854775806までにしてください | |||
| 通話中のアカウントのコールバック先内線IDを更新した場合 | AccountCallbackChangeException | CANNOT_CHANGE_CALLBACK_CAUSE_NOW_CALLING | ステータスの変更に失敗しました 通話中または着信中の可能性があります 時間を置いて再度変更してください | |
| すでに別アカウントのコールバック先内線IDに使用している内線IDに更新した場合 | CANNOT_CHANGE_CALLBACK_CAUSE_NOW_USING | 指定したサインイン端末は既に利用されています | ||
| 通話中の内線IDに更新した場合 | CANNOT_CHANGE_CALLBACK_CAUSE_EXTENSION_NOW_CALLING | 選択した内線番号は通話中または着信中の可能性があります 時間を置いて再度選択してください | ||
| 電話端末以外の内線IDに更新した場合 | INVALID_CALLBACK_CAUSE_INVALID_EXTENSION_TYPE | サインイン端末には電話端末の内線番号を指定してください | ||
| エージェントログイン中のアカウントのコールバック先内線IDを更新した場合 | CANNOT_CHANGE_CALLBACK_CAUSE_NOW_AGENT_LOGIN | エージェントログイン中はサインイン端末を変更することができません | ||
| 存在しない内線IDを指定した場合 | EntityNotFoundException | EntityNotFoundException | 対象が存在しません | |
| callback_phone_number | 「9文字から30文字」以外を入力した場合 | ValidateException | VALIDATE_ERROR | callback_phone_number:9文字から30文字までにしてください |
| 半角数字以外を入力した場合 | callback_phone_number:書式が正しくありません | |||
| 通話中のアカウントのコールバック先外線番号を更新した場合 | AccountCallbackChangeException | CANNOT_CHANGE_CALLBACK_CAUSE_NOW_CALLING | ステータスの変更に失敗しました 通話中または着信中の可能性があります 時間を置いて再度変更してください | |
| 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ライセンスが無効の状態かつ、他のBIZTEL APIが有効状態でリクエストを実行 |
AuthorizationException | FORBIDDEN | This action is unauthorized. |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
3.エージェントステータス参照APIについて
3.1 API基本仕様
URI schemeはエージェントステータス更新APIと同一（2.1 API基本仕様）になります。
3.2 リクエスト方式
エージェントステータス参照APIを実行する際のリクエスト方式は以下となります。
| 認証方式 | HTTPメソッド | URI | 備考 |
|---|---|---|---|
| APIトークン認証方式 | GET | /public/api/v1/account/{id}/status |
APIトークンによるアカウント認証が必要です。 リクエストヘッダにAuthorization: Token (APIトークン)を指定します。 ※アカウント>APIトークンタブから払い出します。詳細は「1.APIトークン」を参照ください。 ※{id}= ステータスを更新するアカウントのIDです。 |
3.3 リクエストパラメータ
| パラメータ | 説明 | 備考 | 必須項目 | パラメータ型 | データ型 | 初期値 |
|---|---|---|---|---|---|---|
| Authorization | API実行のためのトークンを指定する | 'Token トークン文字列'と入力 | Yes | header | string | -- |
| id | アカウントIDを指定します |
必須項目です。 画面での該当項目：アカウントID |
Yes | path | integer | -- |
実行例
● 実行形式
macOSのコンソールで実行する場合の例です。
curl -X GET --header "Accept: application/json" --header "Authorization: Token ★払い出したトークン★" "https://★契約BIZETLサーバFQDN★:8000/public/api/v1/account/★アカウントID★/status"
● 入力サンプル
例）アカウントID：10001 のステータスを参照する。
curl -X GET --header "Accept: application/json" --header "Authorization: Token f165c85da8387829aa27b57a1b8b37d9bd1aab86762ff6cb94dc812790a3b50b3f8c6f21dc051c89" "https://sXXXXXXXXXXXX.u.biztel.jp:8000/public/api/v1/account/10001/status
3.4 レスポンスコード
エージェントステータス参照APIのレスポンスコードは「2.4 レスポンスコード」と同様です。
3.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,no-store,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: Fri,26 May 2023 07:38:11 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: 10
x-ratelimit-remaining: 9
x-robots-tag: noindex
x-xss-protection: 1; mode=block
3.6 レスポンスボディ
エージェントステータス参照APIのレスポンスボディは以下となります。
● 参照成功時の例
{
"id": 10001,
"account_status_id": 10,
"account_status_name": "ログオフ",
"call_status_id": null,
"call_status_name": null,
"callback_extension_id": 10031,
"callback_extension_number": 1001,
"callback_phone_number": null,
"created_at": "2023-05-19 00:00:00",
"updated_at": "2023-05-19 00:00:00",
"version": 1684422000
}
● 参照失敗時の例
{
"name": "AuthenticationException",
"type": "UNAUTHENTICATED",
"exception_id": null,
"message": "Unauthenticated: cause=unknown auth method.",
"messages": null,
"reason": "Unauthenticated: cause=unknown auth method."
}
3.7 レスポンスパラメータ
エージェントステータス参照APIのレスポンスパラメータは以下となります。
| id |
更新したアカウントのIDです。 |
|---|---|
| account_status_id |
アカウントの現在のステータスIDを表示します。 ※お客様にて追加したステータスを取得する場合、そのIDが表示されます。 |
| account_status_name | アカウントの現在のステータスの名前を表示します。 |
| call_status_id |
アカウントの現在の通話ステータスIDです。 |
| call_status_name | アカウントの現在の通話ステータスの名前を表示します。 |
| callback_extension_id | アカウントのサインイン端末のIDを表示します。 |
| call_back_extension_number | アカウントのサインイン端末の内線番号を表示します。 |
| callback_phone_number | アカウントのサインイン端末の外線番号（ダイヤルイン番号）を表示します。 |
| updated_at | アカウント情報が更新された日時を表示します。 |
| created_at | アカウント情報が作成された日時を表示します。 |
| version | 楽観ロックの為のバージョンです。 |
3.8 エラー仕様
エージェントステータス参照APIのエラー仕様は以下となります。
| パラメータ | エラー条件 | name | type | message |
|---|---|---|---|---|
| id | 半角数字以外を入力した場合 | ValidateException | VALIDATE_ERROR | 引数が数値でありません: '{入力文字列}' |
| 「1〜9223372036854775806」以外を入力した場合 | 1〜9223372036854775806までにしてください | |||
| 存在しないアカウント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ライセンスが無効の状態かつ、他のBIZTEL APIが有効状態でリクエストを実行 |
AuthorizationException | FORBIDDEN | This action is unauthorized. |
| 「バーストの単位秒数」に設定した秒数以内に、「バースト時の上限値」を超過するリクエストがあった場合 | AccessLimitException | REQUEST_BURST_LIMIT_EXCEEDED | サーバへの処理リクエストが集中しています。しばらく待ってから操作を再試行してください。 |
4.APIリクエスト数の消費仕様について
BIZTEL API（エージェントステータス更新API）のライセンス消費数は以下となります。
| 認証方式 | ライセンス消費数 | 備考 |
|---|---|---|
| APIトークン認証方式 | １リクエストにつき、１消費 |
累積APIリクエスト数、累積APIレスポンスオブジェクト数ともに１ずつ消費します。 |