利用規約運営会社
EnglishMiiTel へログイン

チュートリアル - Python で音声データを MiiTel に取り込む

Suggest Edits

基本設定

基本的な利用方法は、Incoming Webhook を確認してください。

実装ガイド

Python で 音声データを MiiTel に取り込む方法を Incoming Webhook のサンプルとして紹介します。

事前準備

この手順を実施するには、以下の事前準備が必要です。

  • Python3 をインストールする
  • MiiTel に取り込む音声データ (拡張子はAPI リファレンス の call_data.audio_file_type を参照してください) を用意する

Incoming Webhook の URL を発行する

MiiTel Admin で Incoming webhook の設定に使用する URL を発行します。

詳細は、「Incoming Webhook」を確認してください。

ユーザー ID を確認する

MiiTel Admin で Incoming Webhook の利用許可があるユーザーの ID を確認し、後ほど使えるようにメモしておきます。

フォルダを準備する

作業するためのフォルダを準備して、音声データを格納します。

以下は、Shell でのコマンド例です。(GUI 上から作成したフォルダも利用できます)

mkdir incoming-webhook-test
cp ./test.mp3

Python スクリプトを準備する

ここまで準備できたら、Incoming Webhook で音声を MiiTel に取り込むための Python のコードを作成します。

Incoming Webhook の処理シーケンス図

コードを書く前に、Incoming Webhook の処理シーケンス図を記載します。

Incoming Webhook の処理は、図のとおり2 段階で行われます。

最初に、応対履歴の生成において、取り込む音声の通話種別、電話番号、通話時間などのメタデータ (設定) を含めた POST リクエストを実行します。リクエストに対し MiiTel は、そのメタデータ (設定) に対して応対履歴を生成した上で、音声を登録するための URL を返します。

次に、その URL に対して音声データを PUT リクエストで送信します。

応対履歴生成、音声登録用 URL の発行処理を実行する

まず、取り込む音声のメタデータ (設定) を含めた POST リクエストを実行し、音声登録用 URL を受け取る処理を実行します。

requests モジュールを使うため、インストールします。

pip install requests

今回は、モノラル音声を外線発信として取り込むこととします。URL 生成用の Body は JSON で表すと以下のようになります。

その他のパターンは、「Incoming Webhook 用のエンドポイント」または「Incoming Webhook JSON スキーマ」を参考にしてください。

{
"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": "0660123456",
      "audio_channel_type": "MONAURAL",
      "participants": [
        {
          "type": "FROM",
          "stereo_lr": "left",
          "miitel_user_id": "00000000-0000-0000-0000-000000000000",
          "number": "0312345678",
          "name": "User199"
        },
        {
          "type": "TO",
          "stereo_lr": "right",
          "miitel_user_id": null,
          "number": "0312345678",
          "name": "株式会社RevComm"
        }
      ],
        "tags": [
        {"value": "応対メモテスト"}
      ]
    }
  ]
}

次に、応対履歴、および、音声登録用 URL の生成だけを実行する Python コードを以下のように作成します。

< > で囲っている値は、ご自身の環境に合わせて変更してください。

import json

import requests

# Webhook 用のメタデータを作成

call_data_id = "calldatatest0003"

meta_data = {
    "call_data": [
        {
            "call_data_id": call_data_id,
            "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": "<your-circuit-number>",
            "audio_channel_type": "MONAURAL",
            "participants": [
                {
                    "type": "FROM",
                    "stereo_lr": "left",
                    "miitel_user_id": "<your-miitel-user-id>",
                    "number": "<your-circuit-number>",
                    "name": "User199",
                },
                {
                    "type": "TO",
                    "stereo_lr": "right",
                    "miitel_user_id": None,
                    "number": "0312345678",
                    "name": "株式会社RevComm",
                },
            ],
            "tags": [{"value": "応対メモテスト"}],
        }
    ]
}
url = "<your-incoming-webhook-url>"

# Webhook にメタデータを送信
response = requests.post(
    url, json.dumps(meta_data), headers={"Content-Type": "application/json"}
)

# レスポンスを確認
print(response.status_code)
print(response.json())

🚧

このコードを実行すると、応対履歴が生成されます。不要なデータが生成された場合は、MiiTel Analytics の応対履歴から削除してください。削除方法は「応対履歴を削除する」を確認してください。

上記のコードを実行すると、以下のようなレスポンスを受け取られます。

{'audio_upload_urls': [
      {'calldatatest0003': {
        'url': 'https://call-audio-bucket.miitel.jp/incoming_webhook/uploads/your-tenant-code/00000000-0000-0000-0000-000000000000/018c1146-52ad-bfac-39e7-ef79f262258a/018c1146-52b3-3f11-1828-38cd1e3ba596.mp3?Expires=111111111&Signature=gjMUXX0FXFHlVSOVVj1fQrzNCsUpXsPI7HHZOrP3RDBUY97R-YR~jD1HDbLwb7n3zLldq5TtmhoDHdHKVn~J~-gidNX71Y7GjUqvWKxiMgogqRlYyDnQqpittezEd3URAS2faiGUSSZqOawDnQMWwfiYMgtHJ8wXTvejuUDEiyweP1RVoC9oH0nBWVp1ONOYtVpH3GObmp8FP~PvSQ9EAh0G5bznP4raX5WZzjot9xuEuZeReWGn5U9fFb2~6MlIUJzruCnHwZlCSifZbWysD3HNKL-FIww-f3qeCBHBnesQlW9nPahDm0-sy5cPbU0pDH5WQRlJmyyH3drTKuZPBQ__&Key-Pair-Id=K28QWMK6P8H686',
        'call_data_id': 'calldatatest0003', 
        'call_id': '018c1146-52ad-bfac-39e7-ef79f262258a', 
        'call_detail_id': '018c1146-52ad-bfac-39e7-ef79f262258a'
      }
    }
  ]
}

ここで、この call_data_id ごとに生成された URL に対して音声データを PUT で送信すると、音声を取り込めるようになります。

音声取り込みの処理を実装する

次に、音声取り込みの処理を実装します。

以下のように、Python コードを編集します。

import json

import requests

# Webhook 用のメタデータを作成

call_data_id = "calldatatest0003"

meta_data = {
    "call_data": [
        {
            "call_data_id": call_data_id,
            "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": "<your-circuit-number>",
            "audio_channel_type": "MONAURAL",
            "participants": [
                {
                    "type": "FROM",
                    "stereo_lr": "left",
                    "miitel_user_id": "<your-miitel-user-id>",
                    "number": "<your-circuit-number>",
                    "name": "User199",
                },
                {
                    "type": "TO",
                    "stereo_lr": "right",
                    "miitel_user_id": None,
                    "number": "0312345678",
                    "name": "株式会社RevComm",
                },
            ],
            "tags": [{"value": "応対メモテスト"}],
        }
    ]
}
url = "<your-incoming-webhook-url>"

# Webhook にメタデータを送信
response = requests.post(
    url, json.dumps(meta_data), headers={"Content-Type": "application/json"}
)

# レスポンスを確認
print(response.status_code)
# JSON 形式でレスポンスを確認
print(response.json())

# レスポンスから音声ファイルのアップロード URL を取得
audio_input_url = response.json()["audio_upload_urls"][0][call_data_id]["url"]

# 音声ファイルをアップロード
with open("test.mp3", "rb") as f:
    response = requests.put(audio_input_url, data=f)

# レスポンスを確認
print(response.status_code)

最後のレスポンスに 200 ステータスで返ってきてたら成功です。

MiiTel の応対履歴が以下いずれかの状態であれば、正しく音声が取り込まれています。

  • 分析が完了している
  • 下図のように分析中と書かれたメッセージが表示されている

以上で Python を使って Incoming Webhook で MiiTel に音声を取り込む処理が完了しました。

終わりに

今回は、非常にシンプルな音声の取り込み処理を例に、Incoming Webhook の使い方を紹介しました。

もし、うまく動作しない場合はフォーラム からご質問ください。

こちらを応用して、様々な音声のデータを MiiTel に取り込むことができます。MiiTel Phone を利用できない環境でも、MiiTel の分析基盤を活かした業務設計、システム設計を行えます。

ぜひ、様々なチャレンジをしてみてください。

Updated 5 months ago