Incoming Webhook の仕様と利用方法

Incoming Webhook を利用すると、電話システムと MiiTel を連携し、電話システムの応対履歴を MiiTel Analytics で管理、集計、音声解析できます。

📘

この機能を利用するには ?

  • 管理者権限が必要です。
  • Incoming Webhook の契約が必要です。ご希望のお客様は、弊社担当者、または、サポートへお問い合わせください。

Incoming Webhook の使用準備

まず、Incoming webhook の設定に使用する URL を作成します。

  1. https://account.miitel.jp/v1/signin にアクセスし、管理者権限があるユーザーで MiiTel Analytics にログインします。
  2. 画面右上の [MiiTel Admin を開く] をクリックします。
  3. [外部連携] > [Incoming Webhook] をクリックします。
  4. [URL を作成] をクリックします。
  5. 作成された URL が表示されます。

📘

NOTE

  • 1 つの企業 ID に対して作成できる URL は、1 つのみです。
  • URL を再作成する場合、 ellipsis-v-light__1_.svg > [削除] で作成済み URL を削除後、再度 [URL を作成] をクリックしてください。

次に、応対ユーザーとして使用するユーザーに Incoming webhook の利用を許可し、ユーザー ID を取得します。

  1. [ユーザー] > [ユーザー設定] をクリックします。
  2. 使用するユーザーの ellipsis-v-light__1_.svg > [編集] をクリックします。
  3. 「Incoming Webhook の利用」の [利用許可] にチェックを入れます。
  4. [保存] をクリックします。
  1. Incoming Webhook の利用を許可したユーザーの ellipsis-v-light__1_.svg > [ユーザー ID を確認] をクリックします。
  2. [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
methodPUT
param-
data

Response

StatusDescription
200アップロード完了
403URL が間違っている、または、発行から 3 時間以上経過し期限切れ

上記設定が完了したら、以下を参考に、MiiTel Analytics の応対履歴に正しく応対履歴が作成されているか、エラーが出ていないか確認してください。

  • 「音声ファイルがアップロードされていない、または、アップロード中のため、分析が開始されていません。」というエラーメッセージが表示される場合は「2. 音声ファイルをアップロードする」の設定が実行されていない、または、失敗していると考えられます。
  • 「通話時間が短すぎる、または音声に問題があるため、分析結果が表示されていません。」というエラーメッセージが表示される場合は、パラメータの file_type と音声拡張子が一致しない、または、ファイルが壊れていると考えられます。

音声認識結果の話者を入れ替える

"audio_channel_type": "MONAURAL" で音声ファイルのアップロードリクエストを送信している場合、ユーザーと取引先の話者判定が逆になった応対履歴が作成されることがあります。(正しく話者判定された場合、ユーザーが青色、取引先が赤色で表示されます)

話者判定が逆になった場合、以下手順で話者を入れ替え、適切な話者を設定できます。

  1. https://account.miitel.jp/v1/signin にアクセスし、MiiTel Analytics にログインします。
  2. headphones-solid [応対履歴] をクリックします。
  3. ユーザーと取引先が逆になっている通話履歴を選択します。
  4. グラフ右上の [操作] > [ユーザーと取引先を入れ替える] をクリックします。

📘

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 でなければ必須