カスタムエージェントアシスト連携のためのリソース

このページのリソースは、 CXoneとのカスタムエージェントアシスト統合を計画および実装する際に必要な情報を提供します。

対応するエージェントアプリケーション

MAX は現在、カスタムエージェントアシスト統合で使用するための唯一の対応するエージェントアプリケーションです。

オーディオストリーミング

音声パケットはG711 μlaw 8-bit 8000 kHz raw audioとしてエンコードされます。これはすべてのCXoneテレフォニー音声と同じフォーマットです。

エージェントアシストハブでカスタムエージェントアシスト統合を構成する際、エージェントアシストアプリケーションに送信する音声を選択することができます。コンタクト、エージェント、またはその両方から音声を送信することができます。

各ストリームの開始時に、 CXoneはカスタムエージェントアシストエンドポイントアプリに最初のメッセージを送信します。最初のメッセージには、オーディオストリームがエージェントかコンタクトかを示す streamPerspectiveパラメーターが含まれます：

• "streamPerspective": "RX"：エージェントの電話（エージェントが話している）から送信される音声。
• "streamPerspective": "TX"：エージェントが聞く音声：コンタクトが話している音声、または対話が会議モードの場合は複数の人が話している音声。
• "streamPerspective": "MIX"：エージェントとコンタクトの両方の音声ストリームが含まれています。

個々のWebsocket接続には1つのパースペクティブからの音声しか含まれません。通常、これはTXまたはRXであり、ステレオセパレーションを提供します。両方をミックスした単一モノストリームも可能です。会議モードでインタラクションが発生した場合、受信される音声は設定されたストリームのパースペクティブに依存します。パースペクティブがTXの場合、エージェントを除くすべての参加者からの音声が受信されます。

接続が切断されたり、パケットが失われるなどの問題が発生した場合、カスタムエージェントアシストエンドポイントはWebsocketへの接続を回復しようとします。それは最初に受信したものと同じ新しい認証ハンドシェイクを期待します。

コンタクトが保留になるとWebsocket接続は閉じられます。インタラクションが再開されると新しいWebsocket接続が開始されます。それは元のハンドシェイクと同じものを期待します。

認可

カスタムエージェントアシスト統合で認可を使用することができます。お客様の統合では、プロキシトンネルとエージェントアシストアプリケーションでのリクエストに認証が必要な場合があります。

プロキシトンネルの認証

プロキシトンネルを通過する際にリクエストの認可を必要とするようにしたい場合は、この要件を設計に含める必要があります。ヘッダーや動的トークンベースの認可など、どのような種類の認可も使用できます。選択した認可方法を使用するために、プロキシトンネルを構築する必要があります。

また、 Studioスクリプトで認可を管理するように設定する必要があります：

• ヘッダーベースの認可の場合、スクリプトは送信するリクエストにヘッダーを含める必要があります。
• トークンベースの認可の場合、スクリプトはトークンを要求し、それをキャッシュに保存し、トークンの有効期限を管理する必要があります。トークンの有効期限が切れると、スクリプトは必要に応じて新しいトークンを要求する必要があります。認証サーバーとの通信には、 REST API Studio アクション を使用します。

動的認可を使用する場合、まだ利用可能な認可サーバーがない場合、認可サーバーもセットアップする必要があります。認可サーバーは、スクリプトが要求したときにトークンを提供します。

エージェントアシストアプリケーションの認可

エージェントアシストプロバイダーがすべてのリクエストで認可を必要とする場合、 エージェントアシストハブのカスタムエージェントアシストエンドポイントアプリで設定することができます。

カスタム統合で認可を使用するには、次のことが必要です：

• カスタムエージェントアシスト統合スクリプトで使用する認可ヘッダーを生成します。適用されるすべての構成については、エージェントアシストプロバイダーのドキュメンテーションを参照してください。
• エージェントアシストハブのカスタムエージェントアシストエンドポイントアプリに、必要なヘッダー を追加します。 エージェントアシストアプリケーションをテキストと音声のインタラクションで使用する場合、インタラクションのタイプごとに別々のヘッダーが必要です。ヘッダーを生成する方法については、エージェントアシストプロバイダーのドキュメンテーションを参照してください。

スクリプトで何も設定する必要はありません。カスタムエージェントアシストエンドポイントアプリは、エージェントアシストアプリケーションにヘッダーを渡すことを処理します。

CXoneプラットフォーム設定要件

カスタムエージェントアシスト統合をセットアップするために、 CXoneプラットフォームで必要な設定変更はありません。新しいエージェントアシストアプリケーションを含めるために、既存のスクリプトを修正することができます。ただし、お客様の組織での新しいアプリケーションの使用方法によっては、いくつかの設定が必要な場合があります。次のことが必要になる場合があります。

• 音声または ACDチャット用に新しい チャネル コンタクトがエージェントやボットとインタラクトするための方法です。チャネルは、音声、メール、チャット、ソーシャルメディアなどの可能性があります。を作成します。
• ACD チャット用にの新しいチャットプロファイル を作成します。
• 1つまたは複数のACDスキル を作成し、カスタムエージェントアシストアプリケーションを利用できるようにしたいエージェントに割り当てます。
• 新しいチャネル用に連絡先を作成します。
• 既存の 連絡先 着信連絡先が電話番号やEメールアドレスなどの対話を開始するために使用するエントリポイント。を変更し、新しいスクリプトを起動します。この変更は、カスタムエージェントアシスト統合が完全にテストされ、本稼働に投入する準備が整うまで行わないでください。

シーケンス図

シーケンス図は、カスタムエージェントアシスト統合のさまざまな部分がどのようにインタラクトするか、およびそれらのインタラクションが行われる順序を示します。左上から始まり、ページを前後に移動しながら、インタラクションのタイムラインを表示します。

シーケンス図は、カスタム統合を計画する上で重要なパーツです。CXone、エージェントアシストハブ、プロキシトンネル、エージェントアシストアプリケーションの間のリクエストとレスポンスの流れをマッピングするために使用することができます。また、 Studio のスクリプトの流れを決める際にも役立ちます。

Studioスクリプトの要件とガイドライン

CXoneにエージェントアシストアプリケーションを統合するスクリプトを作成する基礎として、以下のサンプルを使用してください。インバウンドとアウトバウンドのインタラクションには、別々のスクリプトが必要です。次の画像は、インバウンドスクリプトに必要なアクションを示しています。

この画像は、アウトバウンドスクリプトに不可欠なアクションを示しています。

どちらのスクリプトでも、Script Param PayloadSnippetはオプションです。エージェントアシストアプリケーションにパラメーターを渡す必要がある場合のみ、これを含める必要があります。

スクリプトを完成させるには次のことを行わなければなりません。

• エージェントアシストアプリケーションの他のブランチを接続します。
• 必要に応じてその他のアクション、設定、スクリプト作成ロジックを追加し、スクリプトがお客様の環境で必要な機能を果たすようにします。

• オプションとしてスクリプトパラメーターペイロードSnippetアクションに、エージェントアシストプロバイダーに送信するカスタムペイロードJSONが含まれていることを確認します。

• Agent AssistアクションのscriptParamsプロパティが{customPayloadJSON}に設定されていることを確認します。これはカスタムペイロード付きのオプションのSnippetアクションを含む場合にのみ必要です。
• Agent Assistアクションにカスタムエージェントアシストエンドポイント設定アプリを割り当てます。
• Snippetアクションを使用して、スクリプトに初期化スニペットを追加します。エージェントアシストアプリケーションをカスタマイズするために行うことができます。
• アクションコネクタを再構成して、コンタクトフローが適切になるようにし、エラーの起きる可能性がある部分を修正します。
• 追加のスクリプトを完了し、スクリプトをテストします。

Studioでのスクリプティングについてアシストが必要な場合、CXoneアカウント担当者にお問い合わせいただくか、オンラインヘルプのスクリプティングのガイドのセクションを参照するか、NICE CXoneコミュニティサイトにアクセスしてください。

スクリプトパラメーターペイロードスニペット

このスニペットは、Agent Assistactionアクションによってエージェントアシストアプリケーションに渡されるデータを定義します。このコードをスクリプトのSnippetactionアクションに追加します。

DYNAMIC customParam
customParam.param1 = "{value1}"
customParam.param2 = "{value2}"
customParam.param3 = "{value3}"
customParam.param4 = "{value4}"

ASSIGN customParamjson = "{customParam.asJSON()}" 

送信するカスタムペイロードパラメーターがなく、スクリプトパラメータースニペットが必要な場合は、値を割り当てずにスニペット内に変数宣言を含めることができます。たとえば。

DYNAMIC customParam
ASSIGN customParamjson = "{customParam.asJSON()}" 

このスニペットを使用するには、次のようにします。

1. 組織のニーズや使用するエージェントアシストアプリケーションに合わせて、必要に応じてパラメーター名と値を変更します。
2. Snippetアクションを、スクリプト内のAgent Assistアクションの前に配置します。
3. Agent AssistactionアクションのscriptParamsプロパティを、JSONを保持する変数名で構成します。提供された例では、これはcustomParamjsonになります。

新規スクリプトと既存スクリプトの比較

カスタムエージェントアシスト統合で使用する新しいスクリプトを作成することができます。また、既存のスクリプトを修正することも可能です。現在本稼働中のスクリプトに直接変更を加えることはしないでください。このようなことをすると、コンタクトのルーティングが中断されるエラーが発生することがあります。

既存のスクリプトを使用する場合は、スクリプトのコピーを保存し、それを修正してください。カスタム統合が完全にテストされ、実装の準備が整ったら、修正したスクリプトを本稼働に戻すことができます。次のいずれかを実行してスクリプトを本稼働に移行させます。

• 現在本稼働中のスクリプトの名で保存すること。
• スクリプトを使用するために、ポイントオブコンタクト(PoC) 着信連絡先が電話番号やEメールアドレスなどの対話を開始するために使用するエントリポイント。を設定します。連絡先を設定する前に、スクリプトを新しい名前で保存しておきたい場合があります。

プロキシトンネルWebhookの開発および仕様

プロキシトンネルは、 CXoneとお客様のエージェントアシストアプリケーションのエンドポイントとの間のミドルウェアです。すべてのリクエストとレスポンスはこれを通過します。CXoneからのリクエストを、エージェントアシストアプリケーションが理解できる形式に変換する必要があります。同様に、エージェントアシストアプリケーションからのレスポンスを、 CXoneが理解できる形式に変換する必要があります。これらの変換を実現するためには、 CXone とエージェントアシストアプリケーション間のエンドポイントをマッピングする必要があります。

プロキシトンネルは不要です。ただし、統合に含めることが推奨されます。プロキシトンネルには次のようなメリットがあります。

• 管理するデータセンターへのエントリーが1つだけになるため、セキュリティが向上します。
• フェイルオーバーとロードバランシングを提供します。
• CXoneとエージェントアシストプロバイダーのシステム間のプロトコルを変換します。

統合にプロキシトンネルを含めない場合、スクリプトは最初のWebsocketリクエストをWebhook URLに送信します。エージェントアシストアプリケーションが期待するフォーマットでリクエストを送受信するようにスクリプトを設定する必要があります。

次のセクションで説明します：

• カスタムエージェントアシスト統合とプロキシトンネルのエンドポイントに関する重要な事実 。
• 音声インタラクションのためのCXoneからの初期Webソケットリクエストのフォーマット。
• 音声インタラクションのための ハンドシェイクレスポンスのフォーマット。
• チャットインタラクションのためのwebhook 接続のフォーマット。
• リクエストによる設定パラメーター含めるフォーマット。

プロキシトンネルの開発に関する重要なファクト

以下の情報は、プロキシトンネルのエンドポイントを計画および開発する際に役立ちます：

• テキストリレーエンドポイントは HTTPS を使用する必要があります。HTTPでは動作しません。

• オーディオリレーのエンドポイントは、Websocketである必要があります。セキュア（WSS）または非セキュア（WS）があります。

• すべてのプロキシトンネルのエンドポイントは、 NICE CXoneネットワークからの通信を送受信できる必要があります。

• バイナリデータのみがWebhook経由で流れます。

• 音声インタラクションの場合、通話から送信されるデータは音声バイトのみです。通話コントロールや他のメタデータは含まれません。

• カスタムエージェントアシスト統合は、少なくとも2000の同時リクエストに対応しています。

• インタラクションをストリーミングするための有効期限や最大接続時間などはありません。カスタムエージェントアシスト統合により、通話がアクティブである限り、通話を開いたままにすることができます。通話が終了すると、接続は終了します。

• 通話が保留されると、接続は開いたままですが、データは送信されません。

• コンタクトIDは事業単位 テクニカルサポート、請求、およびCXone環境のグローバル設定の管理に使用される高レベルの組織グループごとに固有です。CXoneには、使用できるAPIがあり、contactIDに関するリアルタイムのデータを取得することができます。APIに関するドキュメントを閲覧するには、CXone開発ポータルにアクセスする必要があります。アクセスについては、 CXoneアカウント担当者 にお尋ねください。

Audio Webhookへの接続：初期リクエスト

音声インタラクションは、Websocketリクエスト（WSSまたはWS）を使用する必要があります。CXoneからの最初のWebSocket リクエストは、次のような形式をとります：

 
"authenticationToken": "[header provided in Custom Agent Assist app]",
"executionInfo": {    
      "contactId": 0, 
      "busNo": 0, 
      "requestId": 0,  
      "actionType": "string",  
      "actionId": 0,  
      "scriptName": "string"
},
      "systemTelemetryData": {    
            "consumerProcessHost": "string",  
            "consumerProcessName": "string",  
            "consumerProcessVersion": "string",  
            "inContactClusterAlias": "string",  
            "inContactScriptEngineHost": "string",  
            "consumerMetaData": {  
                  "additionalProp1": "string",
                  "additionalProp2": "string",   
                  "additionalProp3": "string"  
            }
      },
"streamPerspective": "TX/RX/MIX",
"streamsConfiguration": "string",
"appParams": "string",
"appConfig": "string"
			
		

このリクエストのパラメーターについては、本ページのスキーマmpセクションで説明しています：

• authenticationToken、 streamsConfiguration、appParams、 appConfig はすべてWebSocketHookInitializeMessageセクションで説明されています。
• systemTelemetryDataは、独自のセクションで説明されています。
• streamPerspectiveは、独自のセクションで説明されています。

オーディオフックに接続：ハンドシェイクレスポンス

authenticationToken が提供された場合、トークンまたはヘッダーを検証し、ハンドシェイクレスポンスを送信します。レスポンスは、 CXoneWebSocketMessageのクラス形式に従う必要があります：

public class CXOneWebSocketMessage 
{ 
/// Type of command - see CXOneWebSocketCommandType below
public CXOneWebSocketCommandType command { get; set; } 

/// Type of message returned 
public string messageType { get; set; } 

/// Text message 
public string message { get; set; } 

/// Additional parameters 
public object parameters { get; set; } 
)

public enum CXOneWebSocketCommandType
{ 
CONNECT, 
/// When the initial message/auth validation is a success 
CONNECTED, 
/// Message command 
MESSAGE,  
/// Error command, for example when the initial message/auth is invalid 
ERROR
}
		

たとえば。

{
    "command": "CONNECTED",
    "messageType": "COMMAND",
    "message": "BEGIN AUDIO STREAM"
}
		

Websocketで接続するためのコード例：

	
WebSocketReceiveResult result = await webSocket.ReceiveAsync(buffer, CancellationToken.None);
if (result.MessageType == WebSocketMessageType.Text)
{ 
    _logger.LogInformation(string.Concat ("MessageType : ", result.MessageType.ToString()));
    if (buffer == null || buffer?.Length == 0)
    {
       return;
    }
    var message = Encoding.UTF8.GetString(buffer, 0, buffer?.Length ?? 0);
    _logger.LogInformation(string.Concat("On Connected", message));
 
    // Validates initial message
    var initialMessage = JsonConvert.DeserializeObject<WebSocketHookInitializeMessage>(message);
    webSocketHookInitilizeMessage = initialMessage;
    param = JsonConvert.SerializeObject(webSocketHookInitializeMessage.appConfig);
 
    // Send response back to  after successful validation
    CXOneWebSocketMessage connectedMessage = new CXOneWebSocketMessage
    {
       command = CXOneWebSocketCommandType.CONNECTED,
       messageType = "COMMAND", 
       message = "BEGIN AUDIO STREAM"
   }; 

    var jsonResponse = Newtonsoft.Json.JsonConvert.SerializeObject(connectedMessage);
    await webSocket?.SendAsync(buffer: new ArraySegment<byte>(array: Encoding.UTF8.GetBytes(jsonResponse),
             offset: 0,
             count: jsonResponse.Length),
             messageType: WebSocketMessageType.Text,
             endOfMessage: true,
             cancellationToken: CancellationToken.None);
}

else if (result.MessageType == WebSocketMessageType.Binary)
{
// You can read the binary voice data
}		
				
		

例のコードの画像を表示する

このページのスキーマセクションで、次のように説明されています：

• WebSocketHookInitializeMessage
• CXoneWebSocketMessage
• CXoneWebSocketCommandType

テキストフックに接続する

テキストチャットデータを受信するためには、テキストWebhookに接続する必要があります。HTTP/HTTPS リクエストのみが承認されます。

すべてのリクエストには、以下のオブジェクトが含まれます。エージェントアシストハブのカスタムエージェントアシストエンドポイントアプリにひとつを追加する場合だけ、認可ヘッダーは送信されます。認可ヘッダーは不要です。

public class WebHooksMessagesRequest
{
	/// If you provide this information in the configuration, it's included.
	public string authorizationHeader { get; set; }
	public int contactId { get; set; }
	public int busNo { get; set; }
	
	
	/// This will be one of the following: patron, agent, or system
	public string participantId { get; set; }
	
	/// Text of the user input (from participantId)
	public string messageBody { get; set; }
	
	/// Other useful data about the message or that are part of the message, such as images or links.
	public object messageData { get; set; }
	
	/// Configuration blob from エージェントアシストハブ. 
	/// It may only include the configuration identifier for apps that have large amounts of configuration data.
	public object agentAssistAppConfig { get; set; }
}
 	

このコードのパラメーターは、本ページのスキーマセクションで説明しています。

設定パラメーター

エージェントアシストハブであなたがカスタムエージェントアシストエンドポイントアプリを構成する際に、追加のパラメーターを含めることができます。これは、エージェントアシストプロバイダーが、リクエストごとに特定のパラメーターを送信することを要求する場合に便利です。それらは不要です。追加したパラメーターは、WebHooksMessagesRequestオブジェクトの中のagentAssistAppConfigオブジェクトで送信されます。たとえば。

"agentAssistAppConfig":{ 
   "param1": "value1", 
   "param2": "value2",
} 
		

CXoneカスタムエージェントアシスト連携のためのエンドポイント

ここで提供されるAPIエンドポイントは、CXoneからのリクエストの例を取得するために、カスタムエージェントアシスト統合で使用できるインタラクティブな参照です。オリジナルのスキーマを含む追加情報は、APIのSwaggerのドキュメンテーションに掲載されています。

音声ベースのエージェントアシストアプリケーションのためのエンドポイント

GET /agent_assist_audio_websocket_hooks/example-websocket-server：このエンドポイントではWebsocketサーバーのリクエストURLの例を示します。この例は、CXoneaudio websocket hook specificationに準拠しています。

GET /agent_assist_audio_websocket_hooks/initializemessage-example：このエンドポイントではWebsocket初期化メッセージの例を示します。

POST /agent_assist_audio_websocket_hooks/custom-assist-endpoint/initialize-audio-message-example：このエンドポイントでは、最初のリクエストとレスポンスの例を示します。詳細は、WebSocketHookInitializeMessageスキーマおよびCXoneWebSocketMessageスキーマを参照してください。

チャットベースのエージェントアシスタントアプリケーションのためのエンドポイント

POST /agent_assist_text_webhooks/utterance：このエンドポイントでは、テキストベースの発話 連絡先が言うことまたはタイプすること。をリアルタイムで受信し、非同期にエージェントアシスタンスを提供する例を示します。発話は、コンタクトのみ、エージェントのみ、または両方の可能性があります。

スキーマ

以下のセクションでは、カスタムエージェントアシストエンドポイントで使用されるスキーマに関する情報を提供します。スクリプトでこの情報を使用する前に、必ず最新版のSwaggerドキュメントでスキーマを確認してください。

ActionExecutionInfo

実行中のアクションとスクリプトに関する情報が含まれています。

パラメーター	タイプ	詳細
contactId	整数	インタラクションの一意の識別子。
busNo	整数	スクリプトが配置されているCXoneビジネスユニット テクニカルサポート、請求、およびCXone環境のグローバル設定の管理に使用される高レベルの組織グループのID。
requestId	整数	特定のインタラクションにおける各リクエストを識別するための反復番号。リクエストにrequestIdを含めると、レスポンスに含めることができます。 トラブルシューティングなどの問題解決に役立ちます。requestIDが一意な値である場合、ログファイルから単一のリクエスト/レスポンスを探し出すために使用することができます。
actionType	文字列	カスタムエンドポイントへのリクエストを行うアクションタイプ。
actionId	整数	スクリプト内のStudioアクションのID番号。アクションIDは、アクションがスクリプトに追加された順にリストされます。
scriptName	文字列	リクエストを行うスクリプトのパスと名前。

AgentAssistUtterance_V1

メッセージ本文とメッセージに関する情報を含みます。

パラメーター	タイプ	詳細
contactId	整数 ($int64)	スクリプトの現在のインスタンスにおけるコンタクトのID。
busNo	整数 ($int32)	スクリプトが配置されているCXoneビジネスユニット テクニカルサポート、請求、およびCXone環境のグローバル設定の管理に使用される高レベルの組織グループのID。
tenantId	文字列	このパラメーターは不要です。
participantId	文字列	メッセージにコンタクト（顧客）、エージェント（エージェント）または両方（システム）が含まれるかどうかを示します。
messageBody	文字列	メッセージのテキスト。
messageMetaData		messageBodyのメッセージに関する有用なデータを保持するパラメーターを含んでいます。メッセージがチャットメッセージの場合、このパラメーターには、メッセージの一部として送信される画像、リンク、その他のコンテンツも保持することができます。
agentAssistAppConfig		エージェントアシストハブからの構成情報を含みます。大きな構成BLOBを持つエージェントアシストアプリケーションの場合、このオブジェクトは構成識別子のみを含むことができます。 { "agentAssistAppConfig":         { "param1": "value1", "param2": "value2"         } }

CXoneWebSocketCommandType

送信されるコマンドのタイプを定義します。可能な値は次のとおりです：

• 接続。
• 接続済は最初のメッセージや認可の検証に成功したときのためのもの。
• メッセージはメッセージ送信時に使用します。
• エラーは最初のメッセージや認可の検証が無効な場合に使用します。

CXoneWebSocketMessage

エージェントアシストアプリケーションからCXoneに送信されたメッセージが含まれます。

{ additional parameters

}

StreamPerspective

3つの値を持つ文字列配列が含まれます。このパラメーターは、 エージェントアシストハブのカスタムエージェントアシストエンドポイントアプリで作成された参加者の設定を反映します。オーディオストリームが、コンタクトのみ（0 (TX)）、エージェントのみ（1 (RX) ）または組み合わせ（2 (MX)）からの音声を含むかどうかを定義します。

SystemTelemetryData

Studioスクリプトアクションに関連しない APIコンシューマーに関するデータが含まれます。このオブジェクトが含むデータは、デバッグ、請求、レポートなどに有用な場合があります。

{
	< * >:

}

WebSocketHookInitializeMessage

これは、 NICE CXoneメディアサーバーなど、接続中のWebsocketクライアントからの最初のペイロードに対するメッセージ構造です。

{ parameters

}

{ parameters

}