Incoming Webhook

このページは MiiTel Developers に移行しました。「Incoming Webhook の仕様と利用方法」を確認してください。

今後、このページは更新されないため、ご注意ください。

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

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

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

目次

Incoming Webhook の使用準備

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

  1. https://account.miitel.jp/v1/signin にアクセスし、管理者権限があるユーザーで MiiTel Analytics にログインします。
  2. 画面右上の cog-solid [MiiTel Admin を開く] をクリックします。

  3. [外部連携] > [Incoming Webhook] をクリックします。
  4. [URL を作成] をクリックします。
  5. 作成された URL が表示されます。

__________2023-03-08_17.56.53.png

  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. [保存] をクリックします。

__________2023-03-13_16.19.01.png

  1. Incoming Webhook の利用を許可したユーザーの  ellipsis-v-light__1_.svg  > [ユーザー ID を確認] をクリックします。
  2. [ID をコピーする] をクリックします。

__________2023-03-13_16.26.06.png

Incoming Webhook を使用する

1. Incoming Webhook URL にリクエストを送る

以下 URL にアクセスして、リクエスト形式を確認してください。

https://企業 ID.miitel.jp/openapi/index.html#tag/CallWebhookPbx

(「企業 ID」は、お客様組織の企業 ID に変更してください)

 

2. 音声ファイルをアップロードする

1. でリクエストの送信に成功すると、音声ファイルアップロード用の URL を取得できます。以下は、アップロードできる音声ファイル形式です。

  • オーディオチャンネル: ステレオ、モノラル
  • ファイル形式: M4A, MP3, WAV

  IMPORTANT

  •   オーディオチャンネルがモノラルの場合、アップロード後に話者判定するため、話者分離の一部が不正確になる場合があります。

音声ファイルアップロード用の URL へ音声ファイルを PUT で送信します。

Request

  Description
endpoint 応対履歴生成後に返ってきた URL
method PUT
param -
data ファイル

Response

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

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

  • 「音声ファイルがアップロードされていない、または、アップロード中のため、分析が開始されていません。」というエラーメッセージが表示される場合は「2. 音声ファイルをアップロードする」の設定が実行されていない、または、失敗していると考えられます。

Screenshot_2023-03-16_at_11.41.20.png

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

Screenshot_2023-03-16_at_11.42.19.png

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

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

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

Incoming_webhook_swap1.png

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

Incoming_webhook_swap2.png

  NOTE

  •  以下の外部サービスと MiiTel を連携し、音声認識結果を外部サービスに登録するよう設定している場合、[ユーザーと取引先を入れ替える] をクリックすると、入れ替えた音声認識結果で活動履歴が上書きされます。
    Salesforce
    kintone
    HubSpot
  •  以下の Slack 通知ルールを設定している場合、[ユーザーと取引先を入れ替える] をクリックすると以下のように動作します。
    ・音声認識終了後: [ユーザーと取引先を入れ替える] をクリックした場合も Slack 通知が送られる。通知には、話者が入れ替わった音声認識結果が含まれる
    ・音声認識結果 (要約文)を含む: [ユーザーと取引先を入れ替える] をクリック後の Slack 通知に話者が入れ替わった要約文が含まれる
  •  Outgoing Webhook を利用している場合、[ユーザーと取引先を入れ替える] をクリックすると、話者が入れ替わった音声認識結果を含む応対履歴情報が再送信されます。既存の応対履歴情報は上書きされません。
  •  音声認識終了時にメール通知を受けるように設定している場合、[ユーザーと取引先を入れ替える] をクリックした場合もメール通知が送信されます。

補足: リクエストのデータ形式

応対履歴生成リクエストのデータ形式は、以下のとおりです。

"call_data": [
    {
        "call_data_id": str,
        "audio_file_type": str,
        "event_type": str,
        "groupname": str or null,
        "queue_name": str or null,
        "call_starts_at": str(datetime),
        "call_answered_at": str(datetime) or null,
        "call_ends_at": str(datetime),
        "circuit_number": str or null,
        "audio_channel_type": STEREO or MONAURAL, /*未指定は STEREO で処理される*/
        "participants": [
            {
              "type": "FROM" or "TO",
              "stereo_lr": "left" or "right",
              "miitel_user_id": str or null,
              "number": str,
              "name": str or null
            }
        ],
        "tags": [
            {"value": str}
        ]
    }
]

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

この記事は役に立ちましたか?