お問い合わせは https://biztel.jp/support/ から
ご依頼ください

こちらに「ソフトフォン設定」等、調べたいワードをご入力ください。

このセクションの記事

4.通話テキスト取得API

BIZTEL Servicedesk
  • 更新
目的

音声認識サービスにより、テキスト化された通話内容を任意のタイミングで取得し、外部システムへ連携することが可能です。
対象プラン
用語

【音声認識サービス】

通話音声データをソフトウェアが解析してテキスト化するサービスです。

【WebAPI】

汎用的なWeb技術を利用し、インターネットを介して外部システムとの連携を容易にする仕組みです。
外部システムごとにWebAPIで用いるパラメーターは異なり、各システムで仕様を公開しています。

【BIZTEL API】

BIZTELが公開するAPIを示します。
外部システムからBIZTELに対して実行処理や履歴などの取得を行うことができるパラメーターが用意されています。
（通話テキスト取得APIはBIZTEL APIの1つとなります。)
ポイント

・本機能は、BIZTELバージョン 3.7.10 以降で利用可能です。

・本機能をご利用いただく場合、「通話録音」「音声認識連携」「通話テキスト取得API」のライセンス契約が必要です。
※外部連携先の基本契約ライセンスの追加・変更等が必要な場合がございます。
　お客様の契約状況によって異なりますので、詳しくはこちらのフォームよりお問い合わせください。

・本機能をご利用する場合、別途お客様でAmiVoice APIのご契約が必要です。
　ご契約が済んでいない場合、必要情報が不足する為、動作しませんのでご注意ください。
※AmiVoice API以外の音声認識サービスとの連携をご希望の場合は、弊社営業窓口にお問い合わせください。

・月間のAPIリクエスト数、APIレスポンスオブジェクト数の上限は、各100,000件となります。
（「通話テキスト取得API」に関する制限かつBIZTEL API全体での上限となります。）

・本マニュアルはHTML/PHP(PCRE正規表現等)/WebAPIの基礎的な技術知識がある、WEB系開発者様やCRMベンダー様を対象にしております。

目次

1. 通話テキスト取得APIの基本機能

2. 通話テキスト取得APIについて

2.1 API基本仕様

2.2 リクエスト方式

2.3 リクエストパラメータ

2.4 レスポンスコード

2.5 レスポンス例

2.6 エラー仕様

2.7 APIリクエスト数の消費仕様について

1. 通話テキスト取得APIの基本機能

通話テキスト取得APIは、BIZTELと音声認識サービスの連携によりテキスト化された通話内容をダウンロード用APIを使用して外部システムから連携することが可能です。

※通話の終話後など、特定タイミングで取得する場合は、コールアクションの機能にて取得ください
　コールアクションの詳細は「1.コールアクション」を参照ください。

動作イメージ図

mceclip2.png

①BIZTELと音声認識サービスを連携 BIZTELと音声認識サービスが連携済みで、通話内容がテキスト化される状態であることが必須条件です。
②取得コマンドを実行 外部システムからBIZTELで行われた通話のリクエストIDを指定してBIZTELサーバに対して取得コマンドを実行します。
③テキスト内容を返却 取得コマンドを受け取ったBIZTELサーバは指定されたリクエストIDの情報から該当するテキスト内容を返却します。

2. 通話テキスト取得APIについて

2.1 API基本仕様

URI schemeは以下となります。

Host sXXXXXXXXXXXX.u.biztel.jp:8000 BIZTELサーバアドレスとして指定されたFQDN
scheme HTTPS -

2.2 リクエスト方式

通話テキスト取得APIを実行する際のリクエスト方式は以下となります。

認証方式 HTTPメソッド URI 備考
APIトークン認証方式 GET /public/api/v1/monitor/voice_log/(リクエストID)

APIトークンによるアカウント認証が必要です。

リクエストヘッダにAuthorization: Token (APIトークン)を指定します。

※アカウント>APIトークンタブから払い出します。詳細は「1.APIトークン」を参照ください。

※リクエストID＝通知されてきた{ID}の値です。

2.3 リクエストパラメータ

通話テキスト取得APIで使用するパラメータは以下となります。

パラメータ 説明 備考 必須項目 パラメータ型 データ型 初期値
Authorization API実行のためのトークンを指定する 'Token トークン文字列'と入力 Yes header string --
id
 		リクエストIDを指定する 必須項目
画面での該当項目：リクエストID		 YES path string --
format APIの返却値の形式：json(詳細版)、選択なし(簡易版)　 詳細版を利用したい場合はformatにjsonを指定 NO query string -

また、通話テキスト取得APIでは、通話内容のみ取得する簡易版と、日時等の情報を取得できる詳細版でのリクエストが可能です。

※実行結果の例は「2.6 レスポンスボディ」を参照ください。

簡易版での実行例

APIトークン認証方式

■ 通話テキスト取得APIの実行例

macOSのコンソールにて下記コマンドを入力し実行します。

curl -X GET --header 'Accept: application/json' --header 'Authorization: Token ★払い出しトークン★' 'https://★契約BIZTELサーバFQDN★:8000/public/api/v1/monitor/voice_log/★リクエストID★'

 

■ 入力サンプル

curl -X GET --header 'Authorization: Token f7e51c7c8b97963e423d7206d75762b7bba2954efabb64aab5734773bf5e5265bf5d79a7be0f1b97' 'https://sXXXXXXXXXXXX.u.biztel.jp:8000/public/api/v1/monitor/voice_log/21091300000468000050'

※上記★〜★の箇所は、お客様のご利用状況に合わせて変更します。
※curlコマンドを利用する際は必要に応じて、curlコマンドのインストールを行います。

詳細版での実行例

APIトークン認証方式

■ 通話テキスト取得APIの実行例

macOSのコンソールにて下記コマンドを入力し実行します。

curl -X GET --header 'Accept: application/json' --header 'Authorization: Token ★払い出しトークン★' 'https://★契約BIZTELサーバFQDN★:8000/public/api/v1/monitor/voice_log/★リクエストID★'?format=json

 

■ 入力サンプル

curl -X GET --header 'Authorization: Token f7e51c7c8b97963e423d7206d75762b7bba2954efabb64aab5734773bf5e5265bf5d79a7be0f1b97' 'https://sXXXXXXXXXXXX.u.biztel.jp:8000/public/api/v1/monitor/voice_log/21091300000468000050'?format=json

※上記★〜★の箇所は、お客様のご利用状況に合わせて変更します。
※curlコマンドを利用する際は必要に応じて、curlコマンドのインストールを行います。
※詳細版で取得する場合は、APIリクエストパラメータに「?format=json」を指定します。

2.4 レスポンスコード

録音ファイル取得APIを実行する際のレスポンスコードは以下となります。

HTTP Status Code Reason 説明
200 Successful Operation 正常終了（成功）
401 Unauthorized 認証失敗
403

Forbidden

 音声認識連携、通話テキスト取得APIのライセンス契約がありません
404 Not Found

録音ファイルが存在しない場合に出力されます
429 Too Many Requests

バースト上限値を超過した場合
500 Internal Server Error

システム障害

2.5 レスポンス例

簡易版でのレスポンス例

簡易版では、抽出対象の通話に紐づくテキスト内容のみ抽出します。

user@MacBook-Air ~ % curl -X GET --header 'Accept: application/json' --header 'Authorization: Token 払い出しトークン' 'https://XXXXXXXXXXXX.u.biztel.jp:8000/public/api/v1/monitor/voice_log/リクエストID'
お客様 : もしもし。
オペレータ: もしもし。お電話ありがとうございます。〇〇です。
お客様 : お世話になっております。□□です。
オペレータ : お世話になっております。

詳細版でのレスポンス例

詳細版では、抽出対象の通話に紐づくテキスト内容を含めた各種情報を抽出します。
※以下は、見やすいように整形したものとなります。

user@MacBook-Air ~ % curl -X GET --header 'Accept: application/json' --header 'Authorization: Token 払い出しトークン' 'https://XXXXXXXXXXXX.u.biztel.jp:8000/public/api/v1/monitor/voice_log/リクエストID?format=json'
[
{"id":10000,"order":1,"request_id":"リクエストID","speak_start_sec":"1.25","speaker_type":1,"text":"もしもし","voice_duration_sec":"1.34","voice_log_type":"1","created_at":"2023-02-27 11:29:19","updated_at":"2023-02-27 11:29:19"},
{"id":10001,"order":2,"request_id":"リクエストID","speak_start_sec":"2.80","speaker_type":2,"text":"もしもし","voice_duration_sec":"8.64","voice_log_type":"1","created_at":"2023-02-27 11:29:27","updated_at":"2023-02-27 11:29:27"},
{"id":10002,"order":3,"request_id":"リクエストID","speak_start_sec":"11.80","speaker_type":1,"text":"お世話になっております。〇〇です。","voice_duration_sec":"2.50","voice_log_type":"1","created_at":"2023-02-27 11:29:30","updated_at":"2023-02-27 11:29:30"},
{"id":10003,"order":4,"request_id":"リクエストID","speak_start_sec":"14.40","speaker_type":2,"text":"お世話になっております。","voice_duration_sec":"4.13","voice_log_type":"1","created_at":"2023-02-27 11:29:34","updated_at":"2023-02-27 11:29:34"},

詳細版で表示されるカラム詳細

id BIZTELシステム内で管理している一意のIDが表示されます。
order 音声認識が行われた順番が表示されます。
request_id BIZTELシステム内で通話単位で発行される一意のIDが表示されます。
speak_start_sec 発言の開始時間が表示されます。
speaker_type

表示される数字によって発話者を表します。

1：通話相手の発言テキストです。

2：エージェントの発言テキストです。

4：通話相手側でBIZTELサーバとACPサーバの接続に失敗しています。

5：エージェント側でBIZTELサーバとACPサーバの接続に失敗しています。

※上記以外の数字は表示されません。
text 発言内容が表示されます。
voice_duration_sec 音声の秒数が表示されます。
※小数点第三位以下は切り捨てとなります。
voice_log_type

音声認識サービスの種別が表示されます。

１：AmiVoiceAPIによる音声認識です。

２：OMNISによる音声認識です。
created_at 音声テキストの生成日時が表示されます。
updated_at 音声テキストの更新日時が表示されます。

2.6 エラー仕様

パラメータ エラー条件 name type message
Authorization

Authorizationの値が入力されていない

 AuthenticationException FORBIDDEN

This action is unauthorized.

※音声認識連携、または通話テキスト取得APIのライセンスが無効になっています。
Tokenの値が入力されていない（または一致するデータが存在しない） UNAUTHENTICATED

Unauthenticated: method=personal_token, cause=invalid request.
id リクエストIDの値が入力されていない（または一致するデータが存在しない） EntityNotFoundException NOT_FOUND 対象が存在しません
例外エラー InvalidCodeException NO_WAY NO_WAY
256文字以上の値を入力した場合 ValidateException VALIDATE_ERROR 1文字から255文字までにしてください

2.7 APIリクエスト数の消費仕様について

BIZTEL API（録音ファイル取得API）のライセンス消費数は以下となります。

認証方式 ライセンス消費数 備考
APIトークン認証方式 １リクエストにつき、１消費

累積APIリクエスト数、累積APIレスポンスオブジェクト数ともに１づつ消費します。
セクションページに戻る

関連記事