Incoming Webhook の仕様と利用方法
Incoming Webhook を利用すると、電話システムと MiiTel を連携し、電話システムの応対履歴を MiiTel Analytics で管理、集計、音声解析できます。
この機能を利用するには ？
Incoming Webhook の使用準備
まず、Incoming webhook の設定に使用する URL を作成します。
- https://account.miitel.jp/v1/signin にアクセスし、管理者権限があるユーザーで MiiTel Analytics にログインします。
- 画面右上の
[MiiTel Admin を開く] をクリックします。
- [外部連携] > [Incoming Webhook] をクリックします。
- [URL を作成] をクリックします。
- 作成された URL が表示されます。
NOTE
- 1 つの企業 ID に対して作成できる URL は、1 つのみです。
- URL を再作成する場合、
> [削除] で作成済み URL を削除後、再度 [URL を作成] をクリックしてください。
次に、応対ユーザーとして使用するユーザーに Incoming webhook の利用を許可し、ユーザー ID を取得します。
- [ユーザー] > [ユーザー設定] をクリックします。
- 使用するユーザーの
- 「Incoming Webhook の利用」の [利用許可] にチェックを入れます。
- [保存] をクリックします。
- Incoming Webhook の利用を許可したユーザーの
- [ID をコピーする] をクリックします。
Incoming Webhook を使用する
1. Incoming Webhook URL にリクエストを送る（応対履歴生成リクエスト）
以下URLより、Open API をご確認いただけます。
https://developers.miitel.com/reference/createcallcallwebhookpbx
Open API もしくは、本ページ下部に記載している JSON Schema やリクエストサンプルを参考にして、音声登録用の応対履歴生成をリクエストしてください。
2. 音声ファイルをアップロードする
1. でリクエストの送信に成功すると、音声ファイルアップロード用の URL を取得できます。以下は、アップロードできる音声ファイル形式です。
- オーディオチャンネル: ステレオ、モノラル
- ファイル形式: API リファレンス の
call_data.audio_file_typeを参照してください
音声ファイルアップロード用の URL へ音声ファイルを PUT で送信します。
Request
| Description | |
|---|---|
| endpoint | 応対履歴生成後に返ってきた URL |
| method | PUT |
| param | - |
| data |
Response
| Status | Description |
|---|---|
| 200 | アップロード完了 |
| 403 | URL が間違っている、または、発行から 3 時間以上経過し期限切れ |
上記設定が完了したら、以下を参考に、MiiTel Analytics の応対履歴に正しく応対履歴が作成されているか、エラーが出ていないか確認してください。
- 「音声ファイルがアップロードされていない、または、アップロード中のため、分析が開始されていません。」というエラーメッセージが表示される場合は「2. 音声ファイルをアップロードする」の設定が実行されていない、または、失敗していると考えられます。
- 「通話時間が短すぎる、または音声に問題があるため、分析結果が表示されていません。」というエラーメッセージが表示される場合は、パラメータの file_type と音声拡張子が一致しない、または、ファイルが壊れていると考えられます。
文字起こし結果の話者を入れ替える
"audio_channel_type": "MONAURAL" で音声ファイルのアップロードリクエストを送信している場合、ユーザーと取引先の話者判定が逆になった応対履歴が作成されることがあります。(正しく話者判定された場合、ユーザーが青色、取引先が赤色で表示されます)
話者判定が逆になった場合、以下手順で話者を入れ替え、適切な話者を設定できます。
- https://account.miitel.jp/v1/signin にアクセスし、MiiTel Analytics にログインします。
- [応対履歴] をクリックします。
- ユーザーと取引先が逆になっている通話履歴を選択します。
- グラフ右上の [操作] > [ユーザーと取引先を入れ替える] をクリックします。
NOTE
- 以下の外部サービスと MiiTel を連携し、文字起こし結果を外部サービスに登録するよう設定している場合、[ユーザーと取引先を入れ替える] をクリックすると、入れ替えた文字起こし結果で活動履歴が上書きされます。
・ Salesforce
・ kintone
・ HubSpot- 以下の Slack 通知ルールを設定している場合、[ユーザーと取引先を入れ替える] をクリックすると以下のように動作します。
・文字起こし終了後: [ユーザーと取引先を入れ替える] をクリックした場合も Slack 通知が送られる。通知には、話者が入れ替わった文字起こし結果が含まれる
・文字起こし結果 (要約文)を含む: [ユーザーと取引先を入れ替える] をクリック後の Slack 通知に話者が入れ替わった要約文が含まれる- Outgoing Webhook を利用している場合、[ユーザーと取引先を入れ替える] をクリックすると、話者が入れ替わった文字起こし結果を含む応対履歴情報が再送信されます。既存の応対履歴情報は上書きされません。
- 文字起こし終了時にメール通知を受けるように設定している場合、[ユーザーと取引先を入れ替える] をクリックした場合もメール通知が送信されます。
- もし、正常に動作しない場合は、フォーラム からご質問ください
補足: リクエストのデータ形式
リクエストの Schema
応対履歴生成リクエストの JSON Schema は、以下のとおりです。
{
"$schema": "http://json-schema.org/draft-06/schema#",
"$ref": "#/definitions/Welcome",
"definitions": {
"Welcome": {
"type": "object",
"additionalProperties": false,
"properties": {
"call_data": {
"type": "array",
"items": {
"$ref": "#/definitions/CallData"
}
}
},
"required": [
"call_data"
],
"title": "Welcome"
},
"CallData": {
"type": "object",
"additionalProperties": true,
"properties": {
"call_data_id": {
"type": "string"
},
"audio_file_type": {
"type": "string",
"enum": [
"mp3",
"m4a",
"wav"
]
},
"event_type": {
"type": "string",
"enum": [
"EXTENSION",
"OUTGOING_CALL",
"INCOMING_CALL",
"AUTOMATIC_TRANSFER",
"AUTOMATIC_RECORD",
"EXTENSION_TRANSFER",
"OUTGOING_TRANSFER"
]
},
"group_name": {
"type": [
"string",
"null"
]
},
"queue_name": {
"type": [
"string",
"null"
]
},
"call_starts_at": {
"type": "string",
"format": "date-time"
},
"call_answered_at": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "date-time"
}
]
},
"call_ends_at": {
"type": "string",
"format": "date-time"
},
"circuit_number": {
"type": [
"string",
"null"
]
},
"audio_channel_type": {
"type": "string",
"enum": [
"MONAURAL",
"STEREO"
]
},
"participants": {
"type": "array",
"items": {
"$ref": "#/definitions/Participant"
}
},
"tags": {
"type": "array",
"items": {
"$ref": "#/definitions/Tag"
}
}
},
"required": [
"audio_channel_type",
"audio_file_type",
"call_answered_at",
"call_data_id",
"call_ends_at",
"call_starts_at",
"event_type",
"participants"
],
"title": "CallDatum"
},
"Participant": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"FROM",
"TO"
]
},
"stereo_lr": {
"type": "string",
"enum": [
"left",
"right"
]
},
"miitel_user_id": {
"anyOf": [
{
"type": "null"
},
{
"type": "string",
"format": "uuid"
}
]
},
"number": {
"type": "string",
"pattern": "(^[+*#0-9][0-9]*$)|(^Anonymous$)"
},
"name": {
"type": [
"string",
"null"
]
}
},
"required": [
"miitel_user_id",
"name",
"number",
"stereo_lr",
"type"
],
"title": "Participant"
},
"Tag": {
"type": "object",
"additionalProperties": false,
"properties": {
"value": {
"type": "string"
}
},
"required": [
"value"
],
"title": "Tag"
}
}
}
リクエストのサンプル
{
"call_data": [
{
"call_data_id": "test_id",
"audio_file_type": "mp3",
"event_type": "OUTGOING_CALL",
"group_name": "",
"queue_name": "",
"call_starts_at": "2022-12-09T03:41:48+00:00",
"call_answered_at": "2023-11-28T07:26:23+00:00",
"call_ends_at": "2023-11-28T07:29:34+00:00",
"circuit_number": "05011112222",
"audio_channel_type": "STEREO",
"participants": [
{
"type": "FROM",
"stereo_lr": "left",
"miitel_user_id": "9b1d82f5-9845-4158-9c7b-75e7c235d8e7",
"number": "05011112222",
"name": "RevComm太郎"
},
{
"type": "TO",
"stereo_lr": "left",
"miitel_user_id": null,
"number": "05033334444",
"name": null
}
]
}
]
}
{
"call_data": [
{
"call_data_id": "calldatatest0003",
"audio_file_type": "mp3",
"event_type": "OUTGOING_CALL",
"group_name": "",
"queue_name": "",
"call_starts_at": "2023-11-27T15:22:33+0900",
"call_answered_at": "2023-11-27T15:22:40+0900",
"call_ends_at": "2023-11-27T15:36:33+0900",
"circuit_number": "05011112222",
"audio_channel_type": "MONAURAL",
"participants": [
{
"type": "FROM",
"miitel_user_id": "00000000-0000-0000-0000-000000000000",
"number": "05011112222",
"name": "User199"
},
{
"type": "TO",
"miitel_user_id": null,
"number": "05022223333",
"name": "いろは株式会社"
}
],
"tags": [
{
"value": "応対メモテスト"
}
]
}
]
}
NOTE
"event_type"と"participants"の"type"によっては、"miitel_user_id"が必須です。
"event_type" "miitel_user_id" 必須 / 不要 "type" が
“FROM“の場合"type" が
“TO“の場合OUTGOING_CALL:
外線発信
必須 - OUTGOING_TRANSFER:
外線転送
必須 - INCOMING_CALL:
外線着信
- 必須の場合あり *1 AUTOMATIC_TRANSFER:
自動転送
- - EXTENSION:
ユーザー宛内線
必須 必須の場合あり *2
EXTENSION_TRANSFER:
ユーザー宛内線転送
必須 必須の場合あり *2
AUTOMATIC_RECORD:
留守番電話
- - *1:
call_answered_atが null でなければ必須*2: group_name がない場合: 必須
group_name がある場合:call_answered_atが null でなければ必須
トラブルシューティング
応対履歴が作成されない場合の対処方法
応対履歴が作成されない場合、音声ファイルを以下の方法でアップロードしてください。
- 通話録音を入手します。(Zoom から通話録音をダウンロードする方法は「コール レコーディングのアクセスと共有」を確認してください)
- https://account.miitel.jp/v1/signin にアクセスし、MiiTel Analytics にログインします。
- MiiTel Analytics で [応対履歴] をクリックします。
- [ファイルをアップロード] をクリックします。
- 以下を設定します。
- [1] 通話種別: アップロードする通話音声の通話種別を選択する
- [2] MP3 ファイルを直接ドロップまたはファイルを選択: Zoom Phone からダウンロードした MP3 ファイルをドロップ、または、[ファイルを選択] をクリックして設定する
- [3] 発信電話番号: 発信元の電話番号を入力する (半角数字だけ入力できる)
- [4] 着信発信番号: 着信元の電話番号を入力する (半角数字だけ入力できる)
- [5] ユーザー: 通話した MiiTel ユーザー名を選択する
- [6] 開始日時: アップロードする通話音声の開始日時を設定する
- [7] 終了日時: アップロードする通話音声の終了日時を設定する
- [保存] をクリックします。
NOTE
- 各項目に設定した情報は、MiiTel Analytics の応対履歴に表示されます。
- 通話開始後のタイミングで Salesforce 活動履歴連携を設定している場合、この手順で作成した応対履歴に対して Salesforce 活動履歴は自動作成されません。Salesforce に MiiTel 活動履歴を手動登録してください。
文字起こし結果が表示されない場合の対処方法
応対履歴の文字起こし結果が表示されない場合、音声ファイルを以下の方法でアップロードしてください。
- 通話録音を入手します。(Zoom から通話録音をダウンロードする方法は「コール レコーディングのアクセスと共有」を確認してください)
- https://account.miitel.jp/v1/signin にアクセスし、MiiTel Analytics にログインします。
- [応対履歴] をクリックします。
- 画面左で文字起こし結果が表示されない応対履歴を選択します。
- 文字起こし右上の [操作] > [音声ファイルアップロード] をクリックします。
- 手順 1. でダウンロードしたファイルをドラッグ & ドロップ、または、[ファイルを選択] をクリックして選択します。
- 文字起こし結果が表示されたことを確認します。(解析が完了するまで数分かかる場合があります)
NOTE
- 誤った音声ファイルをアップロードした場合は、正しい音声ファイルを再アップロードしてください。
Updated 5 months ago