> 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/chatbot-response-examples.md).

# 会話AI・チャットボットに求めるレスポンス例・機能

## 会話AI・チャットボットに求めるレスポンス例・機能

下記はデジタルヒューマンプラットフォームと接続する際にチャットボットに求めるレスポンスの例や機能です。

通常はチャットボット側が持つAPIに対してデジタルヒューマンプラットフォームから接続しますが、LLM等をつかってチャットボットを作成する場合は下記を参考にしていただけるとスムーズに接続可能です。

## 一般的なチャットボットへのリクエスト例

```json
{
    "bot_id": "string",
    "api_key": "string",
    "session_id": "string",
    "question": "string",
    "stream": true,
}
```

### パラメーター解説

| パラメーター       | データ型    | 説明                                                       | 補足                           |
| ------------ | ------- | -------------------------------------------------------- | ---------------------------- |
| `bot_id`     | string  | チャットボットの識別子です。特定のチャットボットを指定するために使用されます。                  | —                            |
| `api_key`    | string  | APIへのアクセスを認証するためのキーです。セキュリティのために使用され、正当なユーザーであることを確認します。 | —                            |
| `session_id` | string  | ユーザーのセッションを識別するためのIDです。会話のコンテキストを維持するために使用されます。          | —                            |
| `question`   | string  | ユーザーがチャットボットに尋ねる質問です。チャットボットはこの質問に対して応答を生成します。           | —                            |
| `stream`     | boolean | ストリーミングモードを有効にするかどうかを指定します。                              | `true` の場合、応答がリアルタイムに送信されます。 |

#### 他リクエストパラメーターとして渡せる値

* 言語

ユーザーの質問を言語特定した値。

サポートされている言語 :

| **ロケールコード** | **言語名（日本語）**    |
| ----------- | --------------- |
| af          | アフリカーンス語        |
| als         | アレマン語           |
| am          | アムハラ語           |
| an          | アラゴン語           |
| ar          | アラビア語           |
| arz         | エジプト・アラビア語      |
| as          | アッサム語           |
| ast         | アストゥリアス語        |
| av          | アヴァル語           |
| az          | アゼルバイジャン語       |
| azb         | 南アゼルバイジャニ語      |
| ba          | バシキール語          |
| bar         | バイエルン語          |
| bcl         | ビコール語           |
| be          | ベラルーシ語          |
| bg          | ブルガリア語          |
| bh          | ビハール語           |
| bn          | ベンガル語           |
| bo          | チベット語           |
| bpy         | ビシュヌプリヤ語        |
| br          | ブルトン語           |
| bs          | ボスニア語           |
| bxr         | ブリヤート語          |
| ca          | カタルーニャ語         |
| cbk         | チャバカノ語          |
| ce          | チェチェン語          |
| ceb         | セブアノ語           |
| ckb         | 中央クルド語（ソラニ語）    |
| co          | コルシカ語           |
| cs          | チェコ語            |
| cv          | チュヴァシュ語         |
| cy          | ウェールズ語          |
| da          | デンマーク語          |
| de          | ドイツ語            |
| diq         | ザザ語             |
| dsb         | 低地ソルブ語          |
| dty         | ドテリ語            |
| dv          | ディベヒ語           |
| el          | ギリシャ語           |
| eml         | エミリア・ロマーニャ語     |
| en          | 英語              |
| eo          | エスペラント語         |
| es          | スペイン語           |
| et          | エストニア語          |
| eu          | バスク語            |
| fa          | ペルシア語           |
| fi          | フィンランド語         |
| fr          | フランス語           |
| frr         | 北フリジア語          |
| fy          | 西フリジア語          |
| ga          | アイルランド語         |
| gd          | スコットランド・ゲール語    |
| gl          | ガリシア語           |
| gn          | グアラニー語          |
| gom         | ゴア・コンカニ語        |
| gu          | グジャラート語         |
| gv          | マン島語            |
| he          | ヘブライ語           |
| hi          | ヒンディー語          |
| hif         | フィジー・ヒンディー語     |
| hr          | クロアチア語          |
| hsb         | 高地ソルブ語          |
| ht          | ハイチ語（クレオール）     |
| hu          | ハンガリー語          |
| hy          | アルメニア語          |
| ia          | インターリングア        |
| id          | インドネシア語         |
| ie          | インターリング         |
| ilo         | イロカノ語           |
| io          | イド語             |
| is          | アイスランド語         |
| it          | イタリア語           |
| ja          | 日本語             |
| jbo         | ロジバン語           |
| jv          | ジャワ語            |
| ka          | ジョージア語          |
| kk          | カザフ語            |
| km          | クメール語           |
| kn          | カンナダ語           |
| ko          | 韓国語             |
| krc         | カラチャイ・バルカル語     |
| ku          | クルド語            |
| kv          | コミ語             |
| kw          | コーンウォール語        |
| ky          | キルギス語           |
| la          | ラテン語            |
| lb          | ルクセンブルク語        |
| lez         | レズギ語            |
| li          | リンブルフ語          |
| lmo         | ロンバルド語          |
| lo          | ラオ語             |
| lrc         | 北ルリ語            |
| lt          | リトアニア語          |
| lv          | ラトビア語           |
| mai         | マイティリー語         |
| mg          | マダガスカル語         |
| mhr         | 東部マリ語           |
| min         | ミナンカバウ語         |
| mk          | マケドニア語          |
| ml          | マラヤーラム語         |
| mn          | モンゴル語           |
| mr          | マラーティー語         |
| mrj         | 西部マリ語           |
| ms          | マレー語            |
| mt          | マルタ語            |
| mwl         | ミランダ語           |
| my          | ミャンマー語          |
| myv         | エルジャ語           |
| mzn         | マザンダラーン語        |
| nah         | ナワトル語           |
| nap         | ナポリ語            |
| nds         | 低地ドイツ語          |
| ne          | ネパール語           |
| new         | ネワール語           |
| nl          | オランダ語           |
| nn          | ノルウェー語（ニーノシュク）  |
| no          | ノルウェー語          |
| oc          | オック語            |
| or          | オリヤー語（オディア語）    |
| os          | オセット語           |
| pa          | パンジャーブ語         |
| pam         | パンパンガ語          |
| pfl         | プファルツ語          |
| pl          | ポーランド語          |
| pms         | ピエモンテ語          |
| pnb         | 西パンジャーブ語        |
| ps          | パシュトー語          |
| pt          | ポルトガル語          |
| qu          | ケチュア語           |
| rm          | ロマンシュ語          |
| ro          | ルーマニア語          |
| ru          | ロシア語            |
| rue         | ルーシン語           |
| sa          | サンスクリット語        |
| sah         | サハ語（ヤクート語）      |
| sc          | サルデーニャ語         |
| scn         | シチリア語           |
| sco         | スコッツ語           |
| sd          | シンド語            |
| sh          | セルボ・クロアチア語（歴史的） |
| si          | シンハラ語           |
| sk          | スロバキア語          |
| sl          | スロベニア語          |
| so          | ソマリ語            |
| sq          | アルバニア語          |
| sr          | セルビア語           |
| su          | スンダ語            |
| sv          | スウェーデン語         |
| sw          | スワヒリ語           |
| ta          | タミル語            |
| te          | テルグ語            |
| tg          | タジク語            |
| th          | タイ語             |
| tk          | トルクメン語          |
| tl          | タガログ語           |
| tr          | トルコ語            |
| tt          | タタール語           |
| tyv         | トゥヴァ語           |
| ug          | ウイグル語           |
| uk          | ウクライナ語          |
| ur          | ウルドゥー語          |
| uz          | ウズベク語           |
| vec         | ヴェネト語           |
| vep         | ヴェプス語           |
| vi          | ベトナム語           |
| vls         | 西フラマン語          |
| vo          | ヴォラピューク語        |
| wa          | ワロン語            |
| war         | ワライ語            |
| wuu         | 呉語              |
| xal         | カルムイク語          |
| xmf         | メグレル語           |
| yi          | イディッシュ語         |
| yo          | ヨルバ語            |
| yue         | 広東語             |
| zh          | 中国語             |

## チャットボットからのレスポンス(streamなし)

```json
{
   "question": "string",
   "session_id": "string",
   "answer": "string",
   "metadata":"json string",
   "suggest":[{
           "label":"string1",
           "utterance":"string1"
       },
       {
           "label":"string2",
           "utterance":"string2"
       },
       {
           "label":"string3",
           "utterance":"string3"
       }],
}
```

### パラメーター解説

| パラメーター        | データ型        | 説明                                              | 補足                                                                                                                              |
| ------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `question`    | string      | ユーザーがチャットボットに尋ねた質問です。                           | —                                                                                                                               |
| `session_id`  | string      | ユーザーのセッションを識別するためのIDです。会話のコンテキストを維持するために使用されます。 | —                                                                                                                               |
| `answer`      | string      | チャットボットの応答です。ユーザーの質問に対する直接の回答が含まれます。            | 実際に生成・（シナリオベースであれば登録）されている文字列。                                                                                                  |
| `metadata`    | json string | 追加の情報やメタデータを含むJSON形式の文字列です。                     | 一般的に[画面上のコンテンツ表示・非表示用のJSON](https://gitlab.digitalhumans.jp/docs/docs-digitalhumansjp/-/blob/main/development/README.md)が含まれます。 |
| `suggest`     | array       | ユーザーに対する提案のリストです。次に尋ねる可能性のある質問やフレーズが含まれます。      | —                                                                                                                               |
| ┗ `label`     | string      | 提案のラベルです。ユーザーに表示されるテキストです。                      | —                                                                                                                               |
| ┗ `utterance` | string      | 提案されるユーザーの発話です。ラベルに対応する質問やフレーズが含まれます。           | 実質値。                                                                                                                            |

## チャットボットからのレスポンス(stream)

### stream生成中

```json
{
    "chunk": "string"
    "text": "string",
    "final": false,
}
```

#### パラメーター解説

| パラメーター  | データ型    | 説明                                                    | 補足 |
| ------- | ------- | ----------------------------------------------------- | -- |
| `chunk` | string  | 今回生成された文字列です。                                         | —  |
| `text`  | string  | 現在までにstreamで生成された全体の文字列です。                            | —  |
| `final` | boolean | ストリーミングが終了したことを示すフラグです。`false` の場合、応答が生成途中であることを示します。 | —  |

### stream生成終了

```json
{
   "question": "string",
   "session_id": "string",
   "chunk": "string",
   "text": "string",
   "metadata": "json string",
   "suggest":[{
           "label": "string1",
           "utterance": "string1"
       },
       {
           "label": "string2",
           "utterance": "string2"
       },
       {
           "label": "string3",
           "utterance": "string3"
       }
   ],
   "final": true,
}
```

#### パラメーター解説

| パラメーター        | データ型        | 説明                                              | 補足                                                                                                                              |
| ------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `question`    | string      | ユーザーがチャットボットに尋ねた質問です。                           | —                                                                                                                               |
| `session_id`  | string      | ユーザーのセッションを識別するためのIDです。会話のコンテキストを維持するために使用されます。 | —                                                                                                                               |
| `chunk`       | string      | 今回生成された文字列です。                                   | —                                                                                                                               |
| `text`        | string      | 現在までにstreamで生成された全体の文字列です。                      | 実際にデジタルヒューマンの発話に利用する文字列。                                                                                                        |
| `metadata`    | json string | 追加の情報やメタデータを含むJSON形式の文字列です。                     | 一般的に[画面上のコンテンツ表示・非表示用のJSON](https://gitlab.digitalhumans.jp/docs/docs-digitalhumansjp/-/blob/main/development/README.md)が含まれます。 |
| `suggest`     | array       | ユーザーに対する提案のリストです。次に尋ねる可能性のある質問やフレーズが含まれます。      | —                                                                                                                               |
| ┗ `label`     | string      | 提案のラベルです。ユーザーに表示されるテキストです。                      | —                                                                                                                               |
| ┗ `utterance` | string      | 提案されるユーザーの発話です。ラベルに対応する質問やフレーズが含まれます。           | 実質値。                                                                                                                            |
| `final`       | boolean     | ストリーミングが終了したことを示すフラグです。                         | `true` の場合、応答が完全に生成されています。                                                                                                      |

### チャットボットの機能

デジタルヒューマンに実装している機能・デジタルヒューマンの仕様を元に、チャットボット側に求める機能を記載しています。

#### 起動時の回答設定

* **機能説明:** 初回のセッション開始時に、設定された挨拶や案内メッセージを返す機能です。
* **メリット:**
  1. デジタルヒューマン起動時に発話する文言を設定することができます。
  2. ユーザーはすぐにチャットボットがどのように役立つかを理解しやすくなります。

#### サジェステッドレスポンス（クイックリプライ）機能

* **機能説明:** ユーザーに選択肢を提示し、クリックで簡単に応答できる機能です。
* **メリット**:
  1. デジタルヒューマンのUIで、クイックリプライを表示できる機能を利用可能になります。
  2. ユーザーは、提示された選択肢から一つを選ぶだけで、次のステップに進むことができます。
* 補足: レスポンス例のsuggestに利用することが想定されます。表示文字・実際値の２つを設定できるとさらに幅が広がります。

#### 拡張データ機能

* **機能説明:** 回答のほかに、レスポンスに含めるデータをJSON[サポートサイト](https://gitlab.digitalhumans.jp/docs/docs-digitalhumansjp/-/blob/main/development/README.md)形式で登録できる機能です。
* **メリット**:
  1. デジタルヒューマンのUIで、コンテンツ表示を行うことが可能になります。
  2. 会話に関連する画像やグラフ、動画などを表示することで、ユーザーの理解が深まります。
* 補足: レスポンス例のextensionsに利用されることが想定されます。

#### タグ装飾対応

**機能説明** : デジタルヒューマンとの接続では、デジタルヒューマンのアクションやTTS変換のためのSSMLを特定のタグで文章に装飾することで実現します。チャットボットによっては、タグが自動変換されたり、消えてしまったり、特定の形式に変換される処理が含まれている場合がありますが、この機能はタグをそのままの状態で保持することができます。

#### 多言語対応

* **機能説明:** ユーザーの言語に合わせた言語で回答を生成する機能です。
* **メリット**:
  1. デジタルヒューマンの音声認識優先言語選択・言語特定を利用した正確な言語を取得できます。
  2. グローバルなユーザーに対応できます。
* 補足: リクエストパラメータとして、[ユーザーの言語](/dev/chatbot-connection/chatbot-response-examples.md)を渡すことが可能です。

#### state管理機能

* **機能説明**: ユーザーの質問・回答やLLMの回答を特定の名前の変数として、保持する機能です。
* メリット:
  1. ユーザーは一貫性のある会話を楽しむことができ、途中で情報が途切れることがありません。

#### state管理の拡張

* **品詞抽出**

  ユーザーの質問・回答から主となる品詞を抽出して、　stateに格納する機能。

#### 画像認識機能

* **機能説明**: ユーザーの質問とともに画像データをリクエストすることで、画像も認識した回答を生成する機能です。
* 補足: リクエストパラメータとして、[ユーザーのWebカメラ画像](https://gitlab.digitalhumans.jp/docs/docs-digitalhumansjp/-/blob/main/development/README.md#%E4%BB%96%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF%E3%83%BC%E3%81%A8%E3%81%97%E3%81%A6%E6%B8%A1%E3%81%9B%E3%82%8B%E5%80%A4)を渡すことが可能です。

#### 会話リセット機能

**機能説明**：特定のユーザー質問、またはイベントが来た際に、セッションの会話履歴削除などを行い、会話をリセットする機能。

メリット :

1. デジタルヒューマンのUIに会話をリセットするボタンがあります。ユーザーはボタンを押すことで会話をリセットすることが可能です。

#### 応答拡張機能

* **機能説明**: LLMが生成した特定の文字列を認識し、その内容をレスポンスに自動的に組み込む機能です。
* 例 : 「@suggest{リスト型のサジェスト}」という形式で生成されたサジェストを、レスポンスの「suggest」欄に登録します。
* メリット:
  1. LLMのプロンプト次第で、動的サジェステッドレスポンス（クイックリプライ）・動的拡張データのような機構を作成できます。
  2. LLMによる自動化の幅が大幅に増えます。