### Developer サイト内の URL 表記について MiiTel のドメイン変更に伴い、Developer サイト内の一部ページに旧ドメインの URL が記載されている可能性があります。現在、該当箇所の確認および修正を順次進めております。 Incoming Webhook を利用すると、電話システムと MiiTel を連携し、電話システムの通話履歴を MiiTel Analytics で管理、集計、音声解析できます。 ### この機能を利用するには？ - [管理者権限](https://support.miitel.jp/hc/ja/articles/360047220311)が必要です。 - Incoming Webhook の契約が必要です。ご希望のお客様は、弊社担当者、または、[サポート](https://support.miitel.jp/hc/ja/requests/new)へお問い合わせください。 ## Incoming Webhook の使用準備まず、Incoming webhook の設定に使用する URL を作成します。 1. [https://account.miitel.jp/v1/signin](https://account.miitel.jp/v1/signin) にアクセスし、管理者権限があるユーザーで MiiTel Analytics にログインします。 2. ページの左上にある **⋮⋮⋮** アイコンをクリックします。 3. **Admin** をクリックして MiiTel Admin に移動します。 4. \[外部連携] > \[Incoming Webhook] をクリックします。 5. \[URL を作成] をクリックします。 6. 作成された URL が表示されます。

### NOTE - 1 つの企業 ID に対して作成できる URL は、1 つのみです。 - URL を再作成する場合、

> \[削除] で作成済み URL を削除後、再度 \[URL を作成] をクリックしてください。次に、応対ユーザーとして使用するユーザーに Incoming webhook の利用を許可し、ユーザー ID を取得します。 1. \[ユーザー] > \[ユーザー設定] をクリックします。 2. 使用するユーザーの

> \[編集] をクリックします。 3. 「Incoming Webhook の利用」の \[利用許可] にチェックを入れます。 4. \[保存] をクリックします。

5. Incoming Webhook の利用を許可したユーザーの

> \[ユーザー ID を確認] をクリックします。 6. \[ID をコピーする] をクリックします。

## Incoming Webhook を使用する ### 1. Incoming Webhook URL にリクエストを送る（通話履歴生成リクエスト）以下 URL より、Open API をご確認いただけます。 [``](https://developers.miitel.com/reference/call__webhook_call_creation) Open API もしくは、本ページ下部に記載している [JSON Schema](https://developers.miitel.com/docs/incoming-webhook-getting-started#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE-schema) や[リクエストサンプル](https://developers.miitel.com/docs/incoming-webhook-getting-started#%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%81%AE%E3%82%B5%E3%83%B3%E3%83%97%E3%83%AB)を参考にして、音声登録用の通話履歴生成をリクエストしてください。 ### 2. 音声ファイルをアップロードする **1.** でリクエストの送信に成功すると、音声ファイルアップロード用の URL を取得できます。以下は、アップロードできる音声ファイル形式です。 - **オーディオチャンネル**: ステレオ、モノラル - **ファイル形式**: [API リファレンス](https://developers.miitel.com/reference/call__webhook_call_creation) の `call_data.audio_file_type` を参照してください音声ファイルアップロード用の URL へ音声ファイルを PUT で送信します。 #### Request

	Description
endpoint	通話履歴生成後に返ってきた URL
method	PUT
param	-
data

#### Response | **Status** | **Description** | | :--------- | :------------------------------------------------------------ | | 200 | アップロード完了 | | 403 | URL が間違っている、または、発行から 3 時間以上経過し期限切れ | 上記設定が完了したら、以下を参考に、MiiTel Analytics の通話履歴に正しく[通話履歴](https://support.miitel.jp/hc/ja/articles/360029887111)が作成されているか、エラーが出ていないか確認してください。 - 「音声ファイルがアップロードされていない、または、アップロード中のため、分析が開始されていません。」というエラーメッセージが表示される場合は「[2. 音声ファイルをアップロードする](https://developers.miitel.com/docs/incoming-webhook-getting-started#2-%E9%9F%B3%E5%A3%B0%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E3%82%92%E3%82%A2%E3%83%83%E3%83%97%E3%83%AD%E3%83%BC%E3%83%89%E3%81%99%E3%82%8B)」の設定が実行されていない、または、失敗していると考えられます。

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

## 文字起こし結果の話者を入れ替える `"audio_channel_type": "MONAURAL"` で音声ファイルのアップロードリクエストを送信している場合、ユーザーと取引先の話者判定が逆になった通話履歴が作成されることがあります。(正しく話者判定された場合、ユーザーが青色、取引先が赤色で表示されます) 話者判定が逆になった場合、以下手順で話者を入れ替え、適切な話者を設定できます。

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

### NOTE - 以下の外部サービスと MiiTel を連携し、文字起こし結果を外部サービスに登録するよう設定している場合、\[ユーザーと取引先を入れ替える] をクリックすると、入れ替えた文字起こし結果で活動履歴が上書きされます。
・ [Salesforce](https://support.miitel.jp/hc/ja/articles/360030158912) ・ [kintone](https://support.miitel.jp/hc/ja/articles/360034070132) ・ [HubSpot](https://support.miitel.jp/hc/ja/articles/360040626212) - 以下の [Slack 通知ルール](https://support.miitel.jp/hc/ja/articles/360038112452)を設定している場合、\[ユーザーと取引先を入れ替える] をクリックすると以下のように動作します。
・文字起こし終了後: \[ユーザーと取引先を入れ替える] をクリックした場合も Slack 通知が送られる。通知には、話者が入れ替わった文字起こし結果が含まれる・文字起こし結果 (要約文)を含む: \[ユーザーと取引先を入れ替える] をクリック後の Slack 通知に話者が入れ替わった要約文が含まれる - Outgoing Webhook を利用している場合、\[ユーザーと取引先を入れ替える] をクリックすると、話者が入れ替わった文字起こし結果を含む通話履歴情報が再送信されます。既存の通話履歴情報は上書きされません。 - 文字起こし終了時にメール通知を受けるように設定している場合、\[ユーザーと取引先を入れ替える] をクリックした場合もメール通知が送信されます。 - もし、正常に動作しない場合は、[フォーラム](https://developers.miitel.com/discuss) からご質問ください ## 補足: リクエストのデータ形式 ### リクエストの Schema 通話履歴生成リクエストの JSON Schema は、以下のとおりです。 ```Text schema.json { "$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" ], "pattern": "^[+*#0-9][0-9]*$" }, "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", "minLength": 1, "maxLength": 512 } }, "required": [ "value" ], "title": "Tag" } } } ``` ### リクエストのサンプル ```Text 通話履歴生成リクエスト { "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 } ] } ] } ``` ```Text 音声取り込みリクエスト { "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 でなければ必須 ## トラブルシューティング ### 通話履歴が作成されない場合の対処方法通話履歴が作成されない場合、音声ファイルを以下の方法でアップロードしてください。 1. 通話録音を入手します。(Zoom から通話録音をダウンロードする方法は「コールレコーディングのアクセスと共有」を確認してください) 2. [https://account.miitel.jp/v1/signin](https://account.miitel.jp/v1/signin) にアクセスし、MiiTel Analytics にログインします。 3. MiiTel Analytics で \[通話履歴] をクリックします。 4. \[ファイルをアップロード] をクリックします。

5. 以下を設定します。

- \[1] 通話種別: アップロードする通話音声の通話種別を選択する - \[2] MP3 ファイルを直接ドロップまたはファイルを選択: Zoom Phone からダウンロードした MP3 ファイルをドロップ、または、\[ファイルを選択] をクリックして設定する - \[3] 発信電話番号: 発信元の電話番号を入力する (半角数字だけ入力できる) - \[4] 着信発信番号: 着信元の電話番号を入力する (半角数字だけ入力できる) - \[5] ユーザー: 通話した MiiTel ユーザー名を選択する - \[6] 開始日時: アップロードする通話音声の開始日時を設定する - \[7] 終了日時: アップロードする通話音声の終了日時を設定する 6. \[保存] をクリックします。 ### NOTE - 各項目に設定した情報は、MiiTel Analytics の通話履歴に表示されます。

- 通話開始後のタイミングで [Salesforce 活動履歴連携](https://support.miitel.jp/hc/ja/articles/360030158912)を設定している場合、この手順で作成した通話履歴に対して Salesforce 活動履歴は自動作成されません。[Salesforce に MiiTel 活動履歴を手動登録](https://support.miitel.jp/hc/ja/articles/4405160960141)してください。 ### 文字起こし結果が表示されない場合の対処方法通話履歴の文字起こし結果が表示されない場合、音声ファイルを以下の方法でアップロードしてください。 1. 通話録音を入手します。(Zoom から通話録音をダウンロードする方法は「[コールレコーディングのアクセスと共有](https://support.zoom.us/hc/ja/articles/360038521091-%E3%82%B3%E3%83%BC%E3%83%AB-%E3%83%AC%E3%82%B3%E3%83%BC%E3%83%87%E3%82%A3%E3%83%B3%E3%82%B0%E3%81%AE%E3%82%A2%E3%82%AF%E3%82%BB%E3%82%B9%E3%81%A8%E5%85%B1%E6%9C%89#h_01FWHGPQFFKF05ZH03GH8JRT95)」を確認してください) 2. [https://account.miitel.jp/v1/signin](https://account.miitel.jp/v1/signin) にアクセスし、MiiTel Analytics にログインします。 3. \[通話履歴] をクリックします。 4. 画面左で文字起こし結果が表示されない通話履歴を選択します。 5. 文字起こし右上の \[操作] > \[音声ファイルアップロード] をクリックします。

6. 手順 1. でダウンロードしたファイルをドラッグ & ドロップ、または、\[ファイルを選択] をクリックして選択します。 7. 文字起こし結果が表示されたことを確認します。(解析が完了するまで数分かかる場合があります) ### NOTE - 誤った音声ファイルをアップロードした場合は、正しい音声ファイルを再アップロードしてください。