技術設計書テンプレート

技術設計書（TDD）は、システムの詳細を記述するものです。カスタムバーチャルエージェント統合を計画する上で重要な部分です。このページは、カスタムバーチャルエージェント統合のためのTDDを作成するためのガイドです。

このTDDテンプレートの各セクションには、そのセクションの意図するコンテンツ関する例や追加情報が含まれています。可能な限り、例は、テキストバーチャルエージェント統合の例に関連しています。

このTDDガイドと統合例は、独自のカスタム統合を計画する際の出発点として使用してください。ただし、例として提供されているため、TDDもサンプルプロキシトンネルも特定の環境を想定したものではありません。作成するTDDとプロキシトンネルは、組織のユニークなネットワークアーキテクチャと要件を考慮する必要があります。お客様の環境のニーズに適合するように、セクションの追加や削除が必要な場合があります。

概要

この技術設計書は、 [あなたのバーチャルエージェント]とNICE CXoneとのカスタム統合について説明します。統合には、本書で説明する必要のある以下のコンポーネントが含まれます。

プロキシトンネル/ゲートウェイのミドルウェアを含むアーキテクチャ。
CXoneスキル、連絡先、チャネルを含む構成要件。
バーチャルエージェントハブおよびカスタムバーチャルエージェント統合のためのエンドポイント（カスタムExchangeエンドポイント）。
Snippetコードを含むStudioスクリプト。
認証の要件。
バーチャルエージェントの構成、エンドポイント、メッセージ発信の詳細。
Digital ExperienceリッチメディアコンテンツのJSONスキーマ。
リクエストとレスポンスのスキーママッピング。
[アーキテクチャと統合に特有の他のコンポーネント]。

アーキテクチャの概要

するべきこと：統合の概要図を作成する。インタラクションの処理に関与する環境内のすべてのコンポーネントを含めます。これには、プロキシトンネル、バーチャルエージェント、認可サーバーなどが含まれます。概要説明を含めます。特定の部分をより詳細に示す必要がある場合は、追加の図を作成します。

例

これはACDチャットチャネルでのサンプルのテキストバーチャルエージェント統合です。これは統合の例であるため、実際の統合とは異なる点があります：

プロキシトンネルコードは、 NICE CXoneが提供するサンプルオプションの1つです。本ページの例では、C#のコードを使用しています。
プロキシトンネルは、実際のバーチャルエージェントに接続しません。
プロキシトンネルのエンドポイントは、ユーザーが入力したテキストをエコーバックするように設計されています。
このチャネルコンタクトがエージェントやボットとインタラクトするための方法です。チャネルは、音声、メール、チャット、ソーシャルメディアなどの可能性があります。のチャットは、ライブウェブサイトでは設定されていません。チャットチャネルは、 CXoneのポイントオブコンタクト(PoC)ページから取得した直接リンクを通じてテストされます。

これは認可を必要としないシンプルな統合です。

CXone構成

すべきこと： チャネルコンタクトがエージェントやボットとインタラクトするための方法です。チャネルは、音声、メール、チャット、ソーシャルメディアなどの可能性があります。、スキルエージェントのスキル、能力、知識に基づいてインタラクションの配信を自動化するために使用されます、連絡先着信連絡先が電話番号やEメールアドレスなどの対話を開始するために使用するエントリポイント。、キャンペーン、その他関連する CXone構成設定をリストする。統合でDigital Experience (デジタル)チャネルを使用する場合は、Digital Experienceチャネルと必要なデジタルスキルまたはルーティングキューシステムはルーティングキューを使用して、ケースをルーティングするエージェントを決定します。システム管理者はルーティングキューを作成して、特定のケースがそのタイプのケースの専門知識を持つエージェントにルーティングされるようにします。を含めます。詳しくは、リソースページのCXone構成要件をご覧ください。

例

チャネル：ACDチャット。
スキル：IBChat_CEESampleという名のチャットスキル。
連絡先：IBChat_CEESampleという名のチャット連絡先。
キャンペーン：CEESample。

チャネル要件

これは統合の例であるため、チャットプロファイルは不要です。ただし、実際の統合では、このセクションはチャットプロファイルの要件を指定することになります。チャットプロファイルは、チャットウィンドウの外観を定義するものです。このセクションでは、チャットバブルが設置されるウェブサイト上のページや、その他の関連する要件もリストします。

バーチャルエージェントハブ構成

すべきこと：バーチャルエージェントのWebhook URLと、バーチャルエージェントがリクエストと一緒に送信することを要求するパラメーターをリストします。別のタイムアウトが必要だと判断した場合は、このセクションに追加してください。バーチャルエージェントハブのカスタムExchangeエンドポイントの完全な構成プロセスについては、実装ページで説明しています。

例

Webhook URL：https://https://4db3-5-46-62-207.nrgok.io/proxy/performbotexchange
エンドポイントパラメーター：必要なし
カスタムヘッダー（統合バージョン2.0.0および3.0.0のみ）：必要なし。
タイムアウト：変更の必要なし
認可ヘッダー：必要なし
OAuth設定：必要なし
- OAuth URL：該当なし
- OAuthリクエストパラメーター：該当
- OAuthヘッダー：該当なし

統合バージョン1.0.0 では、動的認証はバーチャルエージェントハブではなく、スクリプトで構成する必要があることに注意してください。

Studioスクリプト

すべきこと：カスタムバーチャルエージェント統合のために設計したスクリプトのスクリーンショットを、説明とともに追加します。必要に応じて、変数の説明、スニペットコード、その他の詳細も記載します。詳しくは、スクリプトのガイドラインと要件を参照してください。

チャットスクリプト例

このスクリプトは、サンプル統合で使用したものと同じです。ご自分のスクリプトのベースとして使用できます。また、音声およびデジタルバーチャルエージェント用のスクリプト例も用意されています。

このスクリプトをダウンロード

このスクリプトは、バーチャルエージェントの統合に必要ないくつかの動的データオブジェクトを作成するSnippetアクションから始まります：

intentInfo
nextPromptSequence
nextPromptBehaviors
customPayload
botSessionState

最初のTextbot Exchangeアクションは、バーチャルエージェントが応答するためのインテント連絡先の発言/入力する内容の背後にある意味または目的。連絡先が伝えたいこと、または達成したいこと。をWelcomeインテントとして設定します。バーチャルエージェントが返信すると、botSessionStateとcustomPayloadオブジェクトを入力し、.asjson()関数を使用してJSONに変換します。

最初のTextbot Exchangeアクションには3つの分岐があります：

Error：エラー分岐は、エラーを処理し、コンタクトに適切なメッセージを提供します。
Return Control to Script：このブランチはバーチャルエージェントが会話が完了したこと、またはコンタクトをライブエージェントに転送する必要があることを通知したときに実行されます。
Prompt and Collect Next Response：このブランチは、以下のように、会話を続けます。

スクリプトは、バーチャルエージェントから受け取ったデータをbotsessionState、customPayloadFromBot、intentInfo、nextPromptオブジェクトに渡します。Askcallerアクションは、バーチャルエージェントのレスポンス（nextPrompt）をコンタクトに促します。このアクションには4つの分岐があります：

Error
Return Control to Script
Caller Responded
Default

すべての分岐は2番目のTextbot Exchangeアクションに移動し、 RES変数のコンタクトの次のリクエストを含む適切な情報をバーチャルエージェントに送ります。このTextbot Exchangeはスクリプト内のアクションの最初のインスタンスと同じ分岐を持っています。

サービスエンドポイントの認可

すべきこと：バーチャルエージェントサービスの認可要件を決定します。認可が必要な場合は、TDDのこのセクションを記入します。環境の認可要件を説明する図を作成する。認可リクエストに必要な内容の詳細を記載する。次のことが挙げられます：

認可のタイプ（ヘッダーまたはトークン）。
すべての必要なヘッダーのキー値ペアです。カスタムエクスチェンジバージョン1.0.0をご利用の場合は、ヘッダーの値のみ必要です。
ヘッダーを使用している場合はバーチャルエージェントサービス、トークンを使用している場合は認可サーバーのための構成要件。
トークンを使用している場合は、認可サーバーのURL。
OAuthリクエスト本文とヘッダーに必要なキー値ペアです。
他のOAuth設定をカスタマイズする必要がある、または希望する場合は、それらの変更を指定してください。ヘッダー名、ヘッダー値のプレフィックス、トークンの有効期限を変更することができます。

詳しくは、リソースページの認可セクションを参照してください。

非認可（パブリック）サービスエンドポイントの例

サンプル統合は認可が不要です。次の図は、パブリックサービスのエンドポイントの外観の例を示しています。

この例では、リクエストの発信元はバーチャルエージェントハブです。まずAPIゲートウェイとインタラクトし、次にバーチャルエージェントサービスとインタラクトします。

認定サービスエンドポイントの例

バーチャルエージェントサービスがリクエストの受信に認可を必要とする場合、すべてのリクエストに認可ヘッダーを送信する必要があります。また、認可サーバー（トークンプロバイダー）を必要とする動的認証も利用できます。ヘッダーを使用する統合のアーキテクチャは、前のセクションのパブリックサービスのエンドポイントの例と似ています。次の図は、動的認証の実装例を示しています。

この例では、スクリプトが始まると、認可サーバーにRESTリクエストが行われ、トークンが提供されます。トークンは、Custom Exchange Endpointと一緒に送信されます。トークンが有効である限り、リクエストはバーチャルエージェントサービスに送信することができます。

プロキシトンネル

すべきこと： 以下のようなプロキシトンネルの詳細を決定します：

プロキシトンネルがどのようにホストされるか。
プロキシトンネルがどのような言語で開発されるのか、必要なアプリケーション、依存関係、SDK、拡張パックなど。
プロキシトンネルのフェイルオーバー戦略。

例

プロキシトンネルホスティング

プロキシトンネル例は、テキストバーチャルエージェント統合の例をセットアップする人のローカルマシンでホストされます。

言語

プロキシトンネルはC#で開発する予定です。VS Codeエディタと.NET SDKが必要になります。

フェイルオーバー戦略

これは統合の例であるため、フェイルオーバー戦略は不要です。

バーチャルエージェントのユースケース—プロキシからバーチャルエージェントのエンドポイントマッピング

すべきこと：インタラクション中の各ポイントで使用されるレスポンスとリクエストを示す、詳細なシーケンス図を作成する。CXoneのリクエストとレスポンスのスキーマと、カスタム統合が必要とするバーチャルエージェントサービスをドキュメント化します。このセクションの例では、CXoneのスキーマのみを示しています。詳しくは、リソースページのプロキシトンネルのセクションおよびシーケンス図のセクションを参照してください。

例

シーケンス図とそれに続くすべては、公開時に利用可能なSwaggerに基づく例です。カスタムのバーチャルエージェント統合には、一般公開されているSwagger 中央から外側を指している矢印の付いた正方形。に記述されているスキーマを常に使用します。Custom Exchange Endpointのスキーマは、定期的に更新される場合があります。これがカスタム統合にどのような影響を与えるかについての詳細は、リソースページを参照してください。

リクエストおよびレスポンスのスキーマ

スキーマを文書化する例として、リクエストのスキーマをこのページに掲載しています。カスタムバーチャルエージェント統合スキーマの詳細な説明については、スキーマのページを参照してください。

リクエスト—ExternalIntegrationBotExchangeRequest

パラメーター	タイプ	説明
virtualAgentId	文字列	バーチャルエージェントハブのカスタムExhangeエンドポイント設定アプリに付けられた名前です。アプリが呼び出すバーチャルエージェントを特定するための名前です。
botConfig	オブジェクト	botConfigで定義されるパラメーターについては、本文書の他のセクションで説明します。
userInput	文字列	スクリプトが割り当てられている連絡先着信連絡先が電話番号やEメールアドレスなどの対話を開始するために使用するエントリポイント。から受信したユーザーからのテキスト入力です。
userInputType	Enum	スクリプトが提供するユーザー入力タイプ。
executionInfo	ActionExecutionInfo	スクリプト内のアクション顧客データの収集、メッセージや音楽の再生、エージェントへの連絡先のルーティングなど、Studioスクリプト内のプロセスを実行します。を実行するためのテレメトリデータ。
systemTelemetryData	SystemTelemetryData	デバッグに使用できるデータ。CXoneインフラに関する情報が含まれています。
base64wavFile	文字列	要求のヘッダーを含むBase 64エンコードされたWAV ファイルおよびユーザーの発話連絡先が言うことまたはタイプすること。の音声が含まれます。
botSessionState	オブジェクト	バーチャルエージェントから受信した往復のセッション情報変数に使用できます。
customPayload	オブジェクト	Studioスクリプトのコンテキストから、追加の変数やパラメーターを送信するために使用することができます。
mediaType	文字列	実行中のスクリプトのメディアタイプを示します。

リクエスト—ActionExecutionInfo

パラメーター	タイプ	説明
contactID	整数	インタラクションの一意の識別子。
busNo	整数	テナントテクニカルサポート、請求、およびCXone環境のグローバル設定の管理に使用される高レベルの組織グループの一意の識別子。
requestId	整数	特定のインタラクションにおける各リクエストを識別するための反復番号。
actionType	文字列	Custom Exchange Endpointへのリクエストを行うアクションタイプ。
actionId	整数	スクリプト内のアクション顧客データの収集、メッセージや音楽の再生、エージェントへの連絡先のルーティングなど、Studioスクリプト内のプロセスを実行します。の一意の識別子。アクションIDは、アクションがスクリプトに追加された順にリストされます。
scriptName	文字列	スクリプトの名前。

リクエスト—SystemTelemetryData

パラメーター	タイプ	説明
consumerProccessHost	文字列	APIを呼び出すアプリケーションのホスト名。
consumerProcessName	文字列	API呼び出し元のプロセス名またはアプリケーション名。例えば、 EsnMediaServer.exe。
consumerProcessVersion	文字列	APIを呼び出すアプリケーションの任意のバージョン情報。
inContactClusterAlias	文字列	該当し利用可能な場合は、C7やM33など、 NICE CXoneのクラスターエイリアスを指定します。
inContactScriptEngineHost	文字列	lax-c4cor01または aoa-c32cor01のように、該当し利用可能な場合は、 NICE CXone スクリプトエンジンのホスト名を指定します。
consumerMetaData	オブジェクト	APIコンシューマーに関する任意かつ拡張可能なデータです。

デジタルチャネルのリッチメディアコンテンツ。

Digital Experience（デジタル）チャネルのカスタムバーチャルエージェント統合をセットアップする場合、メッセージのリッチメディアコンテンツに対応させることを選択することができます。リッチメディアコンテンツには、リストピッカー、画像、タイムピッカーなどのコンテンツが含まれます。

すべきこと：リッチメディアコンテンツを送信するために、デジタルスクリプトを構成する。対応させたいリッチメディアを決定し、そのコンテンツのスキーマをTDDのこのセクションに追加します。

例

サンプル統合では、Digital Experienceチャネルを使用していません。ただし、デジタルのチャットチャネルでクイックリプライを行うためのJSONスキーマの例を以下に示します：

"messageContent": {
"type": "PLUGIN",
"payload": {
	"elements": [
	 {
		"id": "Ukm0hRAiA",
		"type": "QUICK_REPLIES",
		"elements": [
				{
					"id": "Akm0hRAiX",
					"type": "TEXT",
					"text": "This is some text"
				},
				{
					"id": "Nkm0hRAiE",
					"type": "BUTTON",
					"text": "Button 1",
					"postback": "click-on-button-1"
				},
				{
				
					"id": "TkGJ6CAiN",
					"type": "BUTTON",
					"text": "Button 2",
					"postback": "click-on-button-2"
				},
				{
					"id": "EyCyTRCi4",
					"type": "BUTTON",
					"text": "Button 3",
					"postback": "click-on-button-3"
				}
			 ]
			}
		]
 	}
}