> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/dev/chatbot-connection/chatbots-integration.md).

# 会話AI・チャットボットとのプラットフォームインテグレーションの概要

## **チャットボット・会話AIとのインテグレーションの概要**

どの様な会話AIやチャットボット、会話プラットフォームでもデジタルヒューマンと統合することができます。

デジタルヒューマンプラットフォームは、あなたが定義するAPI URLにPOSTメソッドで質問リクエスト（ユーザーがデジタルヒューマンに尋ねた内容）を送信し、応答（デジタルヒューマン発話指示）をプラットフォームに返すことで、デジタルヒューマンは発話し、対話を行う事ができます。

![](/files/iJmFlhxa32l0uoDyFP1Q)

## 会話プラットフォームの統合例

まずは、この例の会話プラットフォーム統合を確認してみてください。この統合では、あなたのデジタルヒューマンをDialogflow CX、Wolfram Alpha、Directlineなどに接続する方法を紹介しています。詳細は以下のチュートリアルビデオで説明されています。

{% hint style="warning" %}
下記動画ではCreatorプラットフォームでの設定を行っていますが、現在プラットフォーム移行中のためCreatorプラットフォームを提供しておりません。エンドポイントURLを設定するよりエンドポイントURLをお送り頂ければ、弊社スタッフにて設定いたします。
{% endhint %}

**その他のプラットフォーム統合例**

* [Google Dialogflow integration in Ruby](https://github.com/tgmerritt/orchestration_with_dialogflow_in_ruby)
* [Google Dialogflow integration in Python](https://github.com/tgmerritt/orchestration_in_python)

{% embed url="<https://youtu.be/JS-FQMAMjp0>" %}

## **リクエストの仕様**

### **ヘッダー**

| **Key**      | **Value**        |
| ------------ | ---------------- |
| Content-Type | application/json |

### **ボディ**

JSON

| フィールド          | 型      | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| digitalHumanId | string | デジタルヒューマンのID。PersonaId・SessionIdとは違い、バックエンドで使用されることはありません。                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| metadata       | object | <p>クライアントに関する情報を主とした、会話プラットフォームに渡されるメタデータ。<br><code>personaId</code><br>ペルソナのID<br><code>promptId</code><br>リクエストのID<br><code>sessionId</code><br>ユーザーセッションのID<br><code>userSpokenLocale</code><br>音声認識STTタイプ使用時に検出された言語<br><code>browserDetectedLocales</code><br>ユーザーのブラウザ/デバイスから検出された言語<br><code>userTimezone</code><br>ユーザーのブラウザ/デバイスから検出されたタイムゾーン<br><code>userScreenWidth</code><br>ユーザーのブラウザ/デバイスから検出された画面幅<br><code>userScreenHeight</code><br>ユーザーのブラウザ/デバイスから検出された画面高さ<br><code>userAgent</code><br><a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent">ユーザーエージェントリクエストヘッダー</a><br><code>custom</code><br>- 実装者が望むもの何でも、文字列化されたJSON値などに使用できます。<br>- <code>uneeqInstance.setCustomPromptMetadata</code>を呼び出すことで設定できます。<br>このメタデータフィールド全体は、以下の例のように文字列化されたJSONです。<br></p> |
| prompt         | string | ユーザーの発話文                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

```json
{
  "digital_human_id": "<実際のdigital_human_id>",
  "metadata": {
    "browser_detected_locales": "ja-JP:en-US",
    "custom": {},
    "persona_id": "<実際のpersona_id>",
    "prompt_id": "<実際のprompt_id>",
    "session_id": "<フロントエンドのsession_id>",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "user_screen_height": 1350,
    "user_screen_width": 2560,
    "user_spoken_locale": "ja-jp",
    "user_timezone": "Asia/Tokyo"
  },
  "prompt": "ユーザー発話"
}
```

## **レスポンスの仕様**

返信で送信されるすべての応答は、コンテンツタイプapplication/ jsonのJSON形式である必要があります。応答の本文の有効な形式を以下に示します。

### **有効なレスポンスタイプ**

| **Code** | **Status**   | **Response**                           |
| -------- | ------------ | -------------------------------------- |
| 200      | OK           | `{"response":"ANSWER","metadata": {}}` |
| 400      | Bad Request  | `{ "error": ERROR_DESCRIPTION }`       |
| 403      | Forbidden    | `{ "error": ERROR_DESCRIPTION }`       |
| 500      | Server Error | `{ "error": ERROR_DESCRIPTION }`       |

### **レスポンスフィールドの仕様**

| フィールド    | 型      | 説明                                                                                      |
| -------- | ------ | --------------------------------------------------------------------------------------- |
| response | string | ユーザーがデジタルヒューマンに尋ねた質問への回答。                                                               |
| metadata | object | <p>フロントエンドに渡す情報。<br>Instcutionsを渡すことで画面表示などを行うことも可能です。<br>その他、任意に値を設定することができます。<br></p> |

```json
{
    "response":"日本へようこそ。何かお困りですか?",
    "metadata": {}
}
```

画面表示例：

```json
{
    "response":"日本へようこそ。何かお困りですか?",
    "metadata": {
		    "instructions":{
				    "displayHtml":{
						    "html":"文字列化されたHTML"
				    }
		    }
    }
}
```

## エンドポイントURLを設定する

APIの準備が完了したら、お客様側のオーケストレーションレイヤーや会話AIのエンドポイントをデジタルヒューマンプラットフォームに指定します。

サポートセンター <https://support.digitalhumans.jp/desk> の`エンドポイントURL設定依頼`からお送りください。

| フィールド      | 説明                                                                                                | 例                                    |
| ---------- | ------------------------------------------------------------------------------------------------- | ------------------------------------ |
| Remote URL | チャットボット・会話AIプラットフォームURLを入れてください。この URL はSSL化された https\:// アドレスである必要があり、この URL にのみリクエストを POST します。 | <https://yourdomain.com/secure-url/> |

## **応答時間**

デジタルヒューマンとのインタラクションはリアルタイム性が重要なため、レイテンシーに敏感です。したがって、デジタルヒューマンプラットフォームからのリクエストを処理する際には応答時間が重要な要因となります。

これらの応答時間のサービスレベル目標は、95 パーセンタイル(percentile) で200ms（0.2秒）です。

応答に5000ms（5秒）以上かかると、リクエストはWeb SDKエラーを生成しますが、アバターは応答を続けます。

{% hint style="info" %}
応答に時間がかかる場合は、先に空で応答を返し、その後[SpeakAPI](https://docs.digitalhumans.jp/speak-api-asynchronous)に対して発話リクエストを行ってください。発話文が複数の文書で構成される場合は、**句点や読点で区切って発話指示を出すなど**の制御を入れる事でデジタルヒューマンの発話が早くなり、ユーザー体験が向上します。
{% endhint %}