外部連携用API

本機能は有償です。
本機能の料金を含む利用についての詳細・契約等については、担当営業までご連絡ください。

概要

外部連携用APIを有効にすると、REST APIを使用してVoice X AI Viewerから簡易通話履歴や通話録音ファイルを取得がすることが可能になります。

外部連携用APIの使用方法について

外部連携用APIを使用するには弊社サポートによる対応が必要になります。
外部連携用APIを使用したい場合、担当営業にご相談のうえ、「お問い合わせ」から弊社サポートにご依頼ください。外部連携用APIを利用するために必要となるログインIDとパスワードが発行されます。

APIの制限事項

  • APIリクエストのパラメータ・フォーマットは「Content-Type: application/json」の形式のみを許容します
  • 本システム側の負荷軽減のため、「秒間十数件以上」「1分ごとに24時間常時」といった連続したAPIリクエストがおこなわれた場合、APIの利用に一時的な制限がかけられる可能性があります
  • 一部のAPIは抽出するデータや、出力する項目を絞り込むことが可能です。それらのAPIでは必要なデータだけを取得するよう適切にパラメータ設定をおこなってください

定期的なデータを取得を希望する場合、『オプション機能 – Webフック通知』の利用もご検討ください

APIについて

API エンドポイント
  • https://api.ai.voicex.jp
API一覧

APIについて、各メソッドの名称、HTTPメソッド（GET、POSTなど）、エンドポイントURL、説明は以下です。各APIの詳細については、API一覧以降に記載しています。

メソッドの名称HTTPメソッドエンドポイント説明
外部連携用トークン発行POST/external/token/authentication外部連携用APIを使用するための認証をおこなう
テキスト化情報取得POST/external/get-text-info簡易通話履歴ID(scUniqueid)を指定することで、テキスト化情報の単一取得をおこなう
テキスト解析結果取得POST/external/get-text-analysis簡易通話履歴ID(scUniqueid)とテキスト解析プロンプトID(promptid)を指定することで、テキスト解析結果の単一取得をおこなう
簡易通話履歴検索POST/external/simple-call-history指定した検索条件に一致する簡易通話履歴のリスト取得をおこなう
通話録音ファイル取得POST/external/get-presigned-url簡易通話履歴ID(scUniqueid)と指定することで、それに紐づく通話録音ファイルのダウンロードURLの取得をおこなう

API【外部連携用トークン発行】

API【外部連携用トークン発行】の詳細は以下です。

  • エンドポイント：/external/token/authentication
  • HTTPメソッド：POST
  • 説明：外部連携用APIを使用するための認証をおこなう

外部連携用APIの認証に対して、CIDRフォーマットのIPアドレス制限を複数設定することが可能です。IPアドレス制限はホワイトリスト形式となります。
※このIPアドレス制限は画面ログインのものとは異なる設定です
（例） 「192.168.0.1/32」「192.168.0.2/32」「192.168.0.3/32」の3つが登録されている場合、これらの IP アドレスのいずれかと合致すれば許可されます。「192.168.0.0/16」が登録されている場合、IP アドレスが2番目のオクテットまでと合致すれば許可されます。
IPアドレス制限を設定したい場合、「お問い合わせ」から弊社サポートにご依頼ください。

リクエスト概要
リクエストボディー必須タイプ備考
tenantCode○stringテナントID
loginId○string認証ID
password○stringパスワード
正常終了時のレスポンス例
{
    "code": 0,
    "executionId": "${Lambda実行ID}",
    "message": "認証成功",
    "date": ${Unix Time},
    "data": {
        "name": "${ユーザー名称}",
        "accessToken": "${ｱｸｾｽﾄｰｸﾝ}",
        "refreshToken": "${ﾘﾌﾚｯｼｭﾄｰｸﾝ}",
        "isAdmin": "${管理者権限か}",
        "groups": [${所属するグループID}]
    }
}

API【テキスト化情報取得】

API【テキスト化情報取得】の詳細は以下です。

  • エンドポイント：/external/get-text-info
  • HTTPメソッド：POST
  • 説明：簡易通話履歴ID(scUniqueid)を指定することで、テキスト化情報の単一取得をおこなう
リクエスト概要
リクエストヘッダー必須タイプ備考
Authorization○string“Bearer ${accessToken}”の形式で指定
API【外部連携用トークン発行】で取得したaccessTokenを使用する
（例） Bearer sampleToken1234
リクエストボディー必須タイプ備考
format○number返戻するフォーマットを指定する
1: JSON
2: CSV
scUniqueid○string通話毎のユニークID
field○array:string返戻項目を指定する
※指定可能な返戻項目は以下参照。
[field]に指定可能な返戻項目
transcript会話内容
fileName音声録音ファイル
index話者を示す
1: 電話を掛けた人
2: 電話を受けた人
start会話内容の喋り始めの時間
end会話内容が喋り終わった時間
startMs会話内容の喋り始めの時間(単位：ms)
endMs会話内容が喋り終わった時間(単位：ms)
正常終了時のレスポンス例

＜JSONフォーマットの場合＞

{
    "code": 0,
    "executionId": "${Lambda実行ID}",
    "message": "処理成功",
    "date": ${Unix Time},
    "data": {
    "results": [
      {
        "transcript": "予約したいんですけど メニュー の確認ってできますか",
        "fileName": "1692336939939.wav",
        "index": 1,
        "start": "00:00:00,000",
        "end": "00:00:14,240",
        "startMs": 0,
        "endMs": 14240,
      },
      {
        "transcript": "ヘッドスパとカットです 今週の土曜日の午後3時頃で可能",
        "fileName": "1718078130129.wav",
        "index": 1,
        "start": "00:00:14,240",
        "end": "00:00:24,000",
        "startMs": 14240,
        "endMs": 24000,
      },
      ~~~~~ 省略 ~~~~~
    ]
  }
]

＜CSVフォーマットの場合＞

"transcript","fileName","index","start","end","startMs","endMs"
"予約したいんですけど メニュー の確認ってできますか","1692336939939.wav",1,"00:00:00,000","00:00:14,240",0,14240
"ヘッドスパとカットです 今週の土曜日の午後3時頃で可能","1692336939939.wav",1,"00:00:14,240","00:00:24,000",14240,24000,
JSON/CSV フォーマットのキーに対する説明
キー名項目階層説明
results2VRS v2テキスト化結果
transcript3会話内容
fileName3音声録音ファイル
index3話者を示す
1: 電話を掛けた人
2: 電話を受けた人
start3会話内容の喋り始めの時間
end3会話内容が喋り終わった時間
startMs3会話内容の喋り始めの時間(単位：ms)
endMs3会話内容が喋り終わった時間(単位：ms)

API【テキスト解析結果取得】

API【テキスト解析結果取得】の詳細は以下です。

  • エンドポイント：/external/get-text-analysis
  • HTTPメソッド：POST
  • 説明：簡易通話履歴ID(scUniqueid)とテキスト解析プロンプトID(promptid)を指定することで、テキスト解析結果の単一取得をおこなう
リクエスト概要
リクエストヘッダー必須タイプ備考
Authorization○string“Bearer ${accessToken}”の形式で指定
API【外部連携用トークン発行】で取得したaccessTokenを使用する
（例） Bearer sampleToken1234
リクエストボディー必須タイプ備考
format○number返戻するフォーマットを指定する
1: JSON
2: CSV
scUniqueid○string通話毎のユニークID
promptid○string返戻対象とするテキスト解析プロンプトID
[通話要約の場合] 98f827cafc
[予約判定の場合] 800907caa0
正常終了時のレスポンス例

＜JSONフォーマットの場合＞

{
    "code": 0,
    "executionId": "${Lambda実行ID}",
    "message": "処理成功",
    "date": ${Unix Time},
  "data": {
    "会話タイトル": "予約の確認と希望日時の調整",
    "お客様情報":　{
        "名前": "ニコライバーグマン",
        "連絡先電話番号": "000-000-0000", 
        "連絡先メールアドレス": "不明"
    },
    "要約": "ニコライバーグマン氏がウェア本店に予約をしたいとの要件があり、ヘッドスパとカットのメニューの確認をしました。希望日時は土曜日の午後3時頃でしたが、既に予約が入っていたため、次の週の火曜日の午後3時頃を提案しました。佐藤さんが火曜日の午後3時に予約を受け付けることを了承し、連絡先電話番号を教えました。予約を受け付けた旨を伝え、当日は連絡をしてもらうようにお願いしました。"
  }
}

＜CSVフォーマットの場合＞

"会話タイトル","お客様情報-名前","お客様情報-連絡先電話番号","お客様情報-連絡先メールアドレス","要約"
"予約の確認と希望日時の調整","ニコライバーグマン","000-000-0000","不明","ニコライバーグマン氏がウェア本店に予約をしたいとの要件があり、ヘッドスパとカットのメニューの確認をしました。希望日時は土曜日の午後3時頃でしたが、既に予約が入っていたため、次の週の火曜日の午後3時頃を提案しました。佐藤さんが火曜日の午後3時に予約を受け付けることを了承し、連絡先電話番号を教えました。予約を受け付けた旨を伝え、当日は連絡をしてもらうようにお願いしました。"
JSON/CSV フォーマットのキーに対する説明
キー名項目階層説明
会話タイトル2会話タイトル
お客様情報2お客様の情報
名前3お客様の名前
連絡先電話番号3お客様の連絡先電話番号
連絡先メールアドレス3お客様の連絡先メールアドレス
要約2テキスト解析による通話要約

API【簡易通話履歴検索】

API【簡易通話履歴検索】の詳細は以下です。

  • エンドポイント：/external/simple-call-history
  • HTTPメソッド：POST
  • 説明：指定した検索条件に一致する簡易通話履歴のリスト取得をおこなう
リクエスト概要
リクエストヘッダー必須タイプ備考
Authorization○string“Bearer ${accessToken}”の形式で指定
API【外部連携用トークン発行】で取得したaccessTokenを使用する
（例） Bearer sampleToken1234
リクエストボディー必須タイプ例備考
filter○object検索条件
sc_start_from○string2024-11-01 15:11:07期間（開始日時）
※開始日時～終了日時の期間は2ヵ月以内
sc_start_to○string2024-11-30 23:59:59期間（終了日時）
sc_directionarray:string[‘IN’, ‘OUT’, ‘LOCAL’]通話種別　※配列で指定した種別をor検索
　外線着信：IN
　外線発信：OUT
　内線：LOCAL
sc_calleridnumstring01234567890発信者番号
sc_calleridnamestringなまえ発信者名
sc_dialednumstring01234567890宛先番号
sc_whoansweredstring301受信者番号
recordingTimeobject{ min: 10, max: 30 }録音時間
※最大値は最小値未満にはならない
minnumber録音時間（最小）
maxnumber録音時間（最大）
sc_durationobject{ min: 10, max: 30 }処理時間
※最大値は最小値未満にはならない
minnumber処理時間（最小）
maxnumber処理時間（最大）
sc_uniqueidstringpbx01-1705000000.00000通話毎のユニークID
search_wordstringこんにちは検索キーワード
fieldarray:string[“sc_start”, “recordingTime”]返戻項目を指定する
※指定可能な返戻項目は下記参照。
sortColumnstringrecordingTimeソート対象となるカラム
sortOrderstringasc昇順(asc)/降順(desc)
[field] に指定可能な返戻項目
sc_start着信日時
sc_direction発信か着信か内線か
sc_calleridnum発信者電話番号
sc_calleridname発信者名
sc_dialednum宛先電話番号
sc_duration処理時間
sc_uniqueid通話毎のユニークID
sc_whoanswered応答者電話番号
recordingTime通話時間
_registered登録日時
_updated更新日時
vrsv2vrsv2を利用した内容
　transcript会話内容要約
　transcriptiondetails会話内容
　　transcript会話内容
　　index話者を示す
　　start会話内容の喋り始めの時間
　　end会話内容が喋り終わった時間
　${プロンプトID}テキスト解析結果
※2階層目以降を指定する場合は「.」で連結する。例）例：vrsv2.transcript
正常終了時のレスポンス例
{
    "code": 0,
    "executionId": "${Lambda実行ID}",
    "message": "処理成功",
    "date": ${Unix Time},
    "data": {
        "hits": [
            {
                "sc_te_id": "1",
                "tenantcode": "voixai",
                "sc_start": "${yyyy-mm-dd hh:ii:ss}",
                "sc_direction": "LOCAL",
                "sc_calleridnum": "田中 太郎",
                "sc_dialednum": "09012345678",
                "sc_disposition": "ANSWERED",
                "sc_duration": 100,
                "sc_uniqueid": "pbx01-11111",
                "sc_whoanswered": "09011111111",
                "recordingTime": 80.64,
                "vx_stereo_s3key": "voixai/2023/10/19/17/pbx01-1697702674.23571.wav",
                "registered": "${yyyy-mm-dd hh:ii:ss}",
                "updated": "${yyyy-mm-dd hh:ii:ss}"
                "vrsv2": {
                    "transcript": "はい、レストランです。XXXXXXXXXXXXXXXXXXXXX",
                    "transcriptiondetails": [
                        {
                            "transcript": "はい、レストランです。",
                            "index": 1,
                            "start": "00:00:05,580",
                            "end": "00:00:07,580",
                            "startMs": 5580,
                            "endMs": 7580,
                            "alternative": {
                                "transcript": "はい、レストランです。",
                                "timestamps": "[\"はい、レストランです。\",5.58,7.58]"
                            }
                        }
                    ],
                    "54877a02a3": {
                        "title": "予約判定",
                        "detail": "{\"分類結果\":\"OK\",\"理由\":\"予約が成功したため\"}",
                    },
                    "3339d84ee0": {
                        "title": "通話要約",
                        "detail": "{\n  \"会話タイトル\": \"レストラン予約\",\n  \"お客様情報\": {\n    \"名前\": \"山田\",\n    \"連絡先電話番号\": \"090-3233-3233\",\n    \"連絡先メールアドレス\": \"不明\"\n  },\n  \"要約\": \"はい、レストランでの予約を希望します。日時は10月21日の土曜日の夜7時からで、4名での予約です。お名前は山田さんで、電話番号は090-3233-3233です。お待ちしています。\"\n}",
                    }
                },
            }
            ~~~~~ 省略 ~~~~~
        ],
        "total": 10
    }
}

API【通話録音ファイル取得】

API【通話録音ファイル取得】の詳細は以下です。

  • エンドポイント：/external/get-presigned-url
  • HTTPメソッド：POST
  • 説明：簡易通話履歴ID(scUniqueid)と指定することで、それに紐づく通話録音ファイルのダウンロードURLの取得をおこなう
リクエスト概要
リクエストヘッダー必須タイプ備考
Authorization○string“Bearer ${accessToken}”の形式で指定
API【外部連携用トークン発行】で取得したaccessTokenを使用する
（例） Bearer sampleToken1234
リクエストボディー必須タイプ備考
scUniqueid○string通話毎のユニークID
正常終了時のレスポンス例
{
  code: 0,
  executionId: '239ca13f-6f8b-4145-bc1a-a522a4ce4e69',
  message: '処理成功',
  date: 1733470721046,
  data: {
    getPresignedUrl: 'https://...'
  }
}