すべてのカテゴリ
開発・設置
会話AI・チャットボットとのプラットフォームインテグレーションの概要

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

DHKK版

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

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

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

Notion image

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

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

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

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

リクエストの仕様

ヘッダー

Key
Value
Content-Type
application/json
 

ボディ

JSON

フィールド
型
説明
sid
文字列
この会話セッションを識別する値を設定するためのカスタムフィールドです。アクセストークンを取得する際にこのフィールドに値を設定しない場合、フィールドは空の文字列になります。
fm-custom-data
文字列
新しいセッショントークンの初回リクエスト時に設定されたアドホックな値。詳細については「アクセストークンの取得」を参照してください。
fm-question
文字列
ユーザーがデジタルヒューマンに尋ねた質問。
fm-conversation
文字列
このセッションに関連する以前のレスポンスでプラットフォームに渡された値。このフィールドにJSONオブジェクトが含まれる場合は文字列化されます。
fm-avatar
文字列
プラットフォームが会話プラットフォームに渡すインタラクションに関する文脈データ。このフィールドは文字列化されたJSONです。
fm-avatar['type']
文字列
'type'の可能な値は「WELCOME」と「QUESTION」です。「WELCOME」は新しいセッションが開始されたときに最初のリクエストとして送信され、「ウェルカム」または開始インテントがマッチして実行されるべきことを示します。 ほとんどのNLPエンジンには「開始」ノードがあり、空の入力に応答するようプログラムする必要があるかもしれません（WELCOMEペイロードにはfm-questionの値が含まれないため）。デジタルヒューマンプラットフォームからの後続のすべてのリクエストでは、typeは「QUESTION」になります。
fm-avatar['avatarSessionId']
文字列
セッションを識別するためのランダムに生成されたUUID。この値は各デジタルヒューマンセッションに固有で、会話識別子として使用できます。多くのNLPエンジンには「会話ID」や「コンテキストID」、「セッションID」の概念があり、この値はNLPエンジン内で新しい会話識別子を作成するためによく使用されます。この値は新しい会話ごとに変更されるため、リターンユーザーの識別には使用できません。ユーザー識別は自身のプラットフォーム内で永続化する必要があります。
fm-metadata
文字列
SDKバージョン2.48.0以降に必要 クライアントに関する情報を主とした、会話プラットフォームに渡されるメタデータ。 userSpokenLocale 音声認識STTタイプ使用時に検出された言語 browserDetectedLocales ユーザーのブラウザ/デバイスから検出された言語 userTimezone ユーザーのブラウザ/デバイスから検出されたタイムゾーン userScreenWidth ユーザーのブラウザ/デバイスから検出された画面幅 userScreenHeight ユーザーのブラウザ/デバイスから検出された画面高さ userAgent ユーザーエージェントリクエストヘッダー custom - 実装者が望むもの何でも、文字列化されたJSON値などに使用できます。 - setCustomChatMetadataを呼び出すことで設定できます。 このメタデータフィールド全体は、以下の例のように文字列化されたJSONです。 
{
    "sid": "18220511-b8bb-4164-9d43-dcf4e33e07b1"
    "fm-custom-data": "{}"
    "fm-question": "こんにちは、質問させてください。"
    "fm-conversation":"{}"
    "fm-avatar": "{\"type\":\"WELCOME\", \"avatarSessionId\": \"5d8e685f-aa66-4fa4-9e1b-37365d497314\"}",
    "fm-metadata": "{
      \"userSpokenLocale\":\"en-AU\",
      \"browserDetectedLocales\":\"en-GB\", 
      \"userTimezone\":\"Pacific/Auckland\",
      \"userScreenWidth\":1977,
      \"userScreenHeight\":1343,
      \"userAgent\":\"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36\"},
      \"custom\":\"{\\\"putWhateverYouWant\\\":\\\"anyValue\\\"}\"
    }"
}
 

レスポンスの仕様

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

有効なレスポンスタイプ

Code
Status
Response
200
OK
{ "answer": ANSWER, "matchedContext": MATCHED_CONTEXT, conversationPayload: CONVERSATION_PAYLOAD }
400
Bad Request
{ "error": ERROR_DESCRIPTION }
403
Forbidden
{ "error": ERROR_DESCRIPTION }
500
Server Error
{ "error": ERROR_DESCRIPTION }
 

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

フィールド
型
説明
answer
文字列
ユーザーがデジタルヒューマンに尋ねた質問への回答。これは以下に説明する文字列化されたJSONオブジェクトです。
conversationPayload
文字列
リクエスト間で使用される会話プラットフォームが必要とする情報。この値は次のリクエストでプラットフォームによって返されます。JSONオブジェクトの場合は文字列化する必要があります。
matchedContext
文字列
会話プラットフォームが行ったインテントマッチについてプラットフォームに通知します。
errorDescription
文字列
発生したエラーの説明。（任意）
{
    "answer": "{\"answer\":\"日本へようこそ。何かお困りですか?\",\"instructions\":{}}",
    "matchedContext": "",
    "conversationPayload": "{}"
}
 

JSON 応答形式仕様

Field
Type
Description
answer
String
ユーザーがデジタルヒューマンに質問したことに対する回答をテキストで表示します。
instructions
String
送信されるプラットフォームの指示は、空であっても有効なJSONオブジェクトでなければなりません。
 

エンドポイント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秒）です。

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

 
💡
応答に時間がかかる場合は、先に空で応答を返し、その後下記のSpeakAPIに対して発話リクエストを行ってください。発話文が複数の文書で構成される場合は、句点や読点で区切って発話指示を出すなどの制御を入れる事でデジタルヒューマンの発話が早くなり、ユーザー体験が向上します。
 

SpeakAPIを使用する

メソッド

POST

/api/v1/<uuid>/speak

 

エンドポイント

提供する環境によって変わるので、担当に確認してください。

例：　https://nlp-orch-001.digitalhumans.ne.jp/api/v1/<uuid>/speak

 

リクエストパラメータ

キー
値
必須
備考
uuid
DHKKが発行した識別子
○
デジタルヒューマン株式会社から提供しない限り確認する方法はありません。

POSTデータ（JSON形式）

キー
値
必須
備考
session_id
アバターのセッションID
○
speak_text
発話させたい文字列
○
プレーンな発話文字列に追加して、SynAnim (シンアニム) - シンセティック アニメーションエンジン の制御タグが利用可能です。
instructions
インストラクション
任意、JSON文字列をセットしてください。ただしフロントエンドの種類によって異なります。 ・ ホステッドエクスペリエンスの場合

レスポンス（JSON形式）

キー
値
備考
result
success または error
{message} エラーメッセージ
resultがerrorの場合のみ
 

Crulサンプル

curl -X POST -H "Content-Type: application/json" -d '{"session_id":"<アバターのセッションID>","speak_text":"<発話させたい文字列>","instructions":"<インストラクション>"}' https://nlp-orch-001.digitalhumans.ne.jp/api/v1/<uuid>/speak
 
 
お役に立ちましたか？
😞
😐
🤩

最終更新日 August 2, 2024

miibo（ミーボ）との接続と会話の設定 会話AI・チャットボットに求めるレスポンス例・機能