目次
1. 概要
本章ではビジュアルトークで提供するAPI機能に関する利用想定図や基本情報について説明しています。
1.1 APIの概要
本APIは、ビジュアルトークより通話用URLの発行や、通話状況の確認、通話履歴に関する操作を行うことが出来るHTTPSベースのAPIです。
1.2 利用想定図
一例として、下図のような利用が可能です。
詳細な遷移図の例は以下の通りです。
※API番号は2章にて説明しているAPIリファレンスの番号に対応しています。
1.3 API利用制限
システム的なタイムアウトや利用制限は設けておりませんが、APIの利用に際しては1アクセス/分を最大頻度としていただきますようお願いいたします。
1.4 API基本情報
APIはHTTPSベースのため、cURLやurllibのようなHTTPライブラリのある全ての言語で機能します。
| プロトコル | HTTPS |
|---|---|
| HTTPメソッド | POST |
| 文字コード | UTF-8 |
各APIのレスポンスに含まれるresultCodeとresultMsgの説明については、以下の表をご覧ください。
| resultCode | resultMsg | 説明 |
|---|---|---|
| 200 | OK. | |
| 400 | Request Invalid Status. | 必須パラメータがない場合 パラメータに無効なデータを入力した場合（エラー項目を表示） |
| 403 | incorrect password. | APIパスワードを間違えた場合 |
| not exist number. | 電話番号を間違えた場合 | |
| Access not allowed. | 許可されたIPではない場合 | |
| not exist user. | ユーザが存在しない場合 通話APIでuserIdにシステム管理者を指定した場合 |
|
| 404 | No Data. | |
| 500 | Internal Error. | |
| 1001 | Too Many Data. |
1.5 API利用にあたる必須情報
以下の項目は全APIにおいて必須となります。
| 名称 | 説明 |
|---|---|
| APIパスワード | システム管理者で以下のどちらかを参照。 環境設定 > セキュリティ設定 > API利用制御設定 環境設定 > API利用設定 > API利用制御設定 |
| 企業ID | ログインURL：https://vt.visuamall.com/lt/企業ID/shop/login |
2. APIリファレンス
本章ではビジュアルトークで提供するAPIリファレンスを記載しています。
2.1 通話
通話画面にアクセスするためのオペレーターURLとユーザーURLを発行できます。電話番号、又はメールアドレスを付与してリクエストした場合、指定連絡先にSMS、又はメールでレスポンスボディに含まれるユーザーURL (clUrl)を送信します。
また、その後のAPIのやり取りを行うためのコールID（通話を識別するID）も発行します。
■リクエストボディ
| キー名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| subsIdStr | String | 〇 | 企業ID（文字列） ※必須情報の表を参照 |
| userId | String | 〇 | 通話に利用するオペレーターのログインID |
| apiPassword | String | 〇 | APIパスワード ※必須情報の表を参照 |
| startMode | String | 〇 | 通話開始時の共有モード リモート背面カメラ = "back" リモート前面カメラ = "front" ローカルカメラ = "agent" ビデオ通話 = "facecall" |
| phoneNumber | String | ユーザー電話番号(ハイフンなし) | |
| String | ユーザーメールアドレス |
■レスポンスボディ
| キー名 | タイプ | 説明 |
|---|---|---|
| resultCode | Integer | エラーコード ※API基本情報の表を参照 |
| resultMsg | String | エラーメッセージ ※API基本情報の表を参照 |
| roomId | String | コールID |
| clUrl | String | 通話用URL①(ユーザー用ショートURL) |
| opUrl | String | 通話用URL②(オペレーター用URL) |
■例：リクエスト
-------------------------------
curl -X POST https://vt.visuamall.com/lt/api/call/ -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"subsIdStr\":\"SBsample\",\"userId\":\"sampleOperator\",\"apiPassword\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"startMode\":\"back\"}"
-------------------------------
■例：レスポンス
-------------------------------
{
"resultCode":200,
"resultMsg":"OK.",
"roomId":”yyyyyyyyyyyyyyy”,
"clUrl":"https://vt.visuamall.com/lt/zzzzzz",
"opUrl":"https://vt.visuamall.com/ag/agconn?roomId=xxxxxxxxxxxxxxx&s=back"}
-------------------------------
■備考
opUrl：ログインページを介さず、指定のuserIdのユーザーで通話画面に遷移。通話終了後は通常のログインページに遷移。
SMSの招待メッセージは「招待メッセージ設定」で設定。
メールの招待メッセージは環境設定>API利用設定>招待メッセージ設定から設定。
phoneNumber（SMS送信用）、email（メール送信用）のどちらも入力がなかった場合はレスポンスの返却のみを行う。両方入力された場合はSMS送信が優先となる。
userIdにシステム管理者を指定した場合、エラーコード403を返却。
2.2 通話状況確認
指定のコールIDの通話状態（通話前、通話中、通話終了後）を取得できます。
■リクエストボディ
| キー名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| subsIdStr | String | 〇 | 企業ID（文字列） ※必須情報の表を参照 |
| userId | String | 〇 | 通話に利用するオペレーターのログインID |
| apiPassword | String | 〇 | APIパスワード ※必須情報の表を参照 |
| roomId | String | 〇 | コールID ※「2.1 通話」のレスポンス内容参照 |
■レスポンスボディ
| キー名 | タイプ | 説明 |
|---|---|---|
| resultCode | Integer | エラーコード ※API基本情報の表を参照 |
| resultMsg | String | エラーメッセージ ※API基本情報の表を参照 |
| callStatus | Integer | ・通話前：0 ・通話中：1 ・通話終了後：2 |
■例：リクエスト
-------------------------------
curl -X POST https://vt.visuamall.com/lt/api/getCallStatus -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"subsIdStr\":\"SBsample\",\"userId\":\"sampleOperator\",\"apiPassword\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"roomId\":\”yyyyyyyyyyyyyyy\"}"
-------------------------------
■例：レスポンス
-------------------------------
{
"resultCode":200,
"resultMsg":"OK.",
"callStatus":0}
-------------------------------
2.3 通話履歴確認
検索条件に該当する通話履歴をリストで取得できます。
■リクエストボディ
| キー名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| subsIdStr | String | 〇 | 企業ID（文字列） ※必須情報の表を参照 |
| apiPassword | String | 〇 | APIパスワード ※必須情報の表を参照 |
| startDate | String | 〇 | 開始日指定(yyyymmdd) 8文字を入力 |
| endDate | String | 〇 | 終了日指定(yyyymmdd) 8文字を入力 |
| userId | String | オペレーターのログインID ※部分一致検索 | |
| phoneNumber | String | ユーザー電話番号(ハイフンなし) ※部分一致検索 | |
| String | ユーザーメールアドレス ※部分一致検索 | ||
| category | String | カテゴリ（full Path：「/」で区切り） ※完全一致検索 155文字まで入力可能 |
|
| captureImg | Integer |
キャプチャ画像（0：なし、1：あり） |
|
| Qr | Integer | QR（0：なし、1：あり） | |
| location | Integer | 位置情報（0：なし、1：あり） | |
| Ocr | Integer | OCR（0：なし、1：あり） | |
| video | Integer | 録画（0：なし、1：あり） | |
| chat | Integer | チャット（0：なし、1：あり） | |
| memo | Integer | メモ（0：なし、1：あり） | |
| File | Integer | ファイルアップロード（0：なし、1：あり） | |
| requestId | Integer | リクエストID ※完全一致検索 | |
| roomId | String | コールID ※完全一致検索 ※「2.1 通話」のレスポンス内容参照 |
■レスポンスボディ
| キー名 | タイプ | 説明 |
|---|---|---|
| resultCode | Integer | エラーコード ※API基本情報の表を参照 |
| resultMsg | String | エラーメッセージ ※API基本情報の表を参照 |
| callList | 以下項目を有する通話リスト | |
| →phoneNumber | String | ユーザー電話番号 |
| →startDate | String | 通話開始時間(yyyy/MM/dd HH:mm:ss) |
| →callTime | String | 通話時間(HH:mm:ss) |
| →roomId | String | コールID ※「2.1 通話」のレスポンス内容参照 |
| String | ユーザーメールアドレス | |
| →category | String | カテゴリ（full Path：「/」で区切り） |
| →requestId | Integer | リクエストID |
| →ocr | Integer | OCR（0：なし、1：あり） |
| →location | Integer | 位置情報（0：なし、1：あり） |
| →qr | Integer | QR（0：なし、1：あり） |
| →captureImg | Integer | キャプチャ画像（0：なし、1：あり） |
| →video | Integer | 録画（0：なし、1：あり） |
| →chat | Integer | チャット（0：なし、1：あり） |
| →memo | Integer | メモ（0：なし、1：あり） |
| →file | Integer | ファイルアップロード（0：なし、1：あり） |
■例：リクエスト（2023年4月17日、録画データのある履歴を検索する場合）
-------------------------------
curl -X POST https://vt.visuamall.com/lt/api/log/getCallLog -H "Accept: application/json" -H "Content-Type: application/json" -d "{\"subsIdStr\":\"SBsample\",\"apiPassword\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"startDate\":\"20230417\",\"endDate\":\"20230417\",\"video\":\"1\"}"
-------------------------------
■例：レスポンス
-------------------------------
{
"resultCode":200,
"resultMsg":"OK.",
"callList":
[{
"phoneNumber":"08012345678",
"startDate":"2023/04/17 06:13:06",
"callTime":"00:14:26",
"roomId":"yyyyyyyyyyyyyyy",
"ocr":0,
"location":0,
"qr":0,
"captureImg":1,
"video":1,
"chat":1,
"memo":0,
"file":0}]}
-------------------------------
■備考
入力された任意項目はAND検索で絞り込み。
検索結果がない場合はエラーコード404を返却。
検索結果が1,000件以上の場合はエラーコード1001を返却。
「startDate」のみが入力された場合はstartDate以降のデータを取得。
「endDate」のみが入力された場合はendDate以前のデータを取得。
「location」、「file」は現状では機能リリース前のため、「0：なし」のみ返却される。
2.4 通話履歴ダウンロード
指定したコールIDに紐づく録画ファイルやキャプチャ画像などの実ファイルを取得できます。
■リクエストボディ
| キー名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| subsIdStr | String | 〇 | 企業ID（文字列） ※必須情報の表を参照 |
| apiPassword | String | 〇 | APIパスワード ※必須情報の表を参照 |
| roomId | String | 〇 | コールID ※完全一致検索 |
| ocr | Integer | ダウンロード：1 | |
| location | Integer | ダウンロード：1 | |
| qr | Integer | ダウンロード：1 | |
| captureImg | Integer | ダウンロード：1 | |
| video | Integer | ダウンロード：1 | |
| chat | Integer | ダウンロード：1 | |
| memo | Integer | ダウンロード：1 | |
| file | Integer | ダウンロード：1 |
■レスポンスボディ（エラー発生時のみ。正常であればファイルがダウンロードされる。）
| キー名 | タイプ | 説明 |
|---|---|---|
| resultCode | Integer | エラーコード ※API基本情報の表を参照 |
| resultMsg | String | エラーメッセージ ※API基本情報の表を参照 |
■例：リクエスト（コールIDがyyyyyyyyyyyyyyyの録画動画とキャプチャ画像の取得）
-------------------------------
curl -X POST https://vt.visuamall.com/lt/api/log/downloadCallLog -o sample.zip -H "Accept: application/json" -H "Content-Type: application/json" -d "{ \"subsIdStr\":\"SBsample\",\"apiPassword\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"roomId\":\"yyyyyyyyyyyyyyy\", \"captureImg\":1, \"video\":1}"
-------------------------------
■備考
任意項目がダウンロード対象であり、「1」を指定することでダウンロードできる。
ファイルは一つのzipファイルとしてダウンロードされる。
ダウンロードに失敗した場合のみレスポンスを返却。
任意項目を１つも指定しない、または該当データが存在しない場合、解凍できない空のzipファイルがダウンロードされる。
2.5 通話履歴削除
検索条件に該当する通話履歴を削除します。
■リクエストボディ
| キー名 | タイプ | 必須 | 説明 |
|---|---|---|---|
| subsIdStr | String | 〇 | 企業ID（文字列） ※必須情報の表を参照 |
| apiPassword | String | 〇 | APIパスワード ※必須情報の表を参照 |
| startDate | String | 開始日指定(yyyymmdd) 8文字を入力 |
|
| endDate | String | 終了日指定(yyyymmdd) 8文字を入力 |
|
| roomId | String | コールID ※完全一致検索 | |
| requestId | Integer | リクエストID ※完全一致検索 | |
| phoneNumber | String | ユーザー電話番号（ハイフンなし） ※完全一致検索 | |
| userId | String | オペレーターのログインID ※完全一致検索 | |
| category | String | カテゴリ（full Path：「/」で区切り） ※完全一致検索 155文字まで入力可能 |
■レスポンスボディ
| キー名 | タイプ | 説明 |
|---|---|---|
| resultCode | Integer | エラーコード ※API基本情報の表を参照 |
| resultMsg | String | エラーメッセージ ※API基本情報の表を参照 |
| resultCount | String | 削除した件数 |
■例：リクエスト（ログインIDがsampleOperatorの履歴のうち2022年度のものを削除）
-------------------------------
curl -X POST https://vt.visuamall.com/lt/api/log/deleteCallLog -H "Accept: application/json" -H "Content-Type: application/json" -d "{ \"subsIdStr\":\"SBsample\",\"apiPassword\":\"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\",\"startDate\":\"20220401\",\"endDate\":\"20230331\",\"userId\":\"sampleOperator\"}"
-------------------------------
■例：レスポンス
-------------------------------
{
"resultCode":200,
"resultMsg":"OK.",
"resultCount":"2件"}
-------------------------------
■備考
入力された任意項目はAND検索で絞り込み。
検索結果がない場合はエラーコード404を返却。
企業IDとAPIパスワードのみの入力の場合は履歴の削除を行わず、エラーコード403を返却。
「startDate」のみが入力された場合はstartDate以降のデータを削除。
「endDate」のみが入力された場合はendDate以前のデータを削除。