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

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

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

MAXを使用でき、Agentアプリケーションははでカスタムエージェントアシスト統合での使用がサポートされています。

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

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

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

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

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

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

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

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

認可

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

プロキシトンネルの認証

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

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

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

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

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

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

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

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

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

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

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

シーケンス図

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

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

カスタムエージェントアシスト統合のシーケンス図の例。

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

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

OnAnswerアクションがRest APIアクションに接続され、エージェントアシストアクションに接続されているスクリプト例。

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

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

スクリプトの設定を完了するには：

  • Agent AssistアクションにCustom Agent Assist Endpoints設定アプリを割り当てます。

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

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

Studioでのスクリプト記述でサポートが必要な場合は、アカウント担当者に連絡するか、オンラインヘルプのテクニカルリファレンスガイドセクションを参照してください。または、Studio{ 9} のコミュニティ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になります。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • コンタクトIDはビジネスユニットClosed CXone環境におけるテクニカルサポート、請求、およびグローバル設定を管理するために使用される上位レベルの組織グループごとに固有です。 CXoneには、使用できるAPIがあり、contactIDに関するリアルタイムのデータを取得することができます。 APIに関するドキュメントを閲覧するには、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 が提供された場合、トークンまたはヘッダーを検証し、ハンドシェイクレスポンスを送信します。 レスポンスは、 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
}
コードエディタから見たサンプルコードのイメージ。

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

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

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

すべてのリクエストには、以下のオブジェクトが含まれます。 Agent Assist HubのCustom Agent Assist Endpointsアプリにひとつを追加する場合だけ、認可ヘッダーは送信されます。 認可ヘッダーは不要です。


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 Agent Assist Hub. 
	/// It may only include the configuration identifier for apps that have large amounts of configuration data.
	public object agentAssistAppConfig { get; set; }
}

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

設定パラメーター

Agent Assist HubのCustom Agent Assist Endpointsアプリを設定する際に、追加のパラメーターを含めることができます。 これは、エージェントアシストプロバイダーが、リクエストごとに特定のパラメーターを送信することを要求する場合に便利です。 それらは不要です。 追加したパラメーターは、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：このエンドポイントでは、テキストベースの発話Closed コンタクトが発言または入力すること。をリアルタイムで受信し、非同期にエージェントアシスタンスを提供する例を示します。 発話は、コンタクトのみ、エージェントのみ、または両方の可能性があります。

スキーマ

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

ActionExecutionInfo

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

パラメーター

タイプ

詳細
contactId 整数 インタラクションの一意の識別子。
busNo 整数 スクリプトが配置されているCXoneビジネスユニットClosed CXone環境におけるテクニカルサポート、請求、およびグローバル設定を管理するために使用される上位レベルの組織グループのID。
requestId 整数

特定のインタラクションにおける各リクエストを識別するための反復番号。 リクエストにrequestIdを含めると、レスポンスに含めることができます。

トラブルシューティングなどの問題解決に役立ちます。 requestIDが一意な値である場合、ログファイルから単一のリクエスト/レスポンスを探し出すために使用することができます。
actionType

文字列

 カスタムエンドポイントへのリクエストを行うアクションタイプ。
actionId

整数

 スクリプト内のStudioアクションのID番号。 アクションIDは、アクションがスクリプトに追加された順にリストされます。
scriptName

文字列

 リクエストを行うスクリプトのパスと名前。

AgentAssistUtterance_V1

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

パラメーター

タイプ

詳細
contactId 整数 ($int64) スクリプトの現在のインスタンスにおけるコンタクトのID。
busNo 整数 ($int32) スクリプトが配置されているCXoneビジネスユニットClosed CXone環境におけるテクニカルサポート、請求、およびグローバル設定を管理するために使用される上位レベルの組織グループのID。
tenantId

文字列

 このパラメーターは不要です。
participantId

文字列

 メッセージにコンタクト（顧客）、エージェント（エージェント）または両方（システム）が含まれるかどうかを示します。
messageBody

文字列

 メッセージのテキスト。
messageMetaData  

messageBodyのメッセージに関する有用なデータを保持するパラメーターを含んでいます。 メッセージがチャットメッセージの場合、このパラメーターには、メッセージの一部として送信される画像、リンク、その他のコンテンツも保持することができます。
agentAssistAppConfig  

Agent Assist Hubからの構成情報を含みます。 大きな構成BLOBを持つエージェントアシストアプリケーションの場合、このオブジェクトは構成識別子のみを含むことができます。

{
	"agentAssistAppConfig":
        {

"param1": "value1",

"param2": "value2"

        }

}

CXoneWebSocketCommandType

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

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

CXoneWebSocketMessage

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

パラメーター

タイプ

詳細
command 文字列 CXOneWebSocketCommandTypeの値が含まれます。
messageType

文字列

 メッセージのタイプを含みます。
message

文字列

 メッセージのテキストを含みます。
parameters  

エージェントアシストアプリケーションが必要とする追加パラメーターを含むオブジェクト。 Agent Assist Hubのカスタムエージェントアシストエンドポイントアプリに含める必要のあるパラメーターを設定します。

{ additional parameters
}

StreamPerspective

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

SystemTelemetryData

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

パラメーター

タイプ

詳細
consumerProcessHost 文字列 APIを呼び出すアプリケーションのホスト名。
consumerProcessName 文字列 APIコールを行っているプロセスまたはアプリケーションの名前。 例えば、 EsnMediaServer.exe。
consumerProcessVersion 文字列 APIを呼び出すアプリケーションの任意のバージョン情報。
inContactClusterAlias 文字列 該当し、利用可能な場合は、スクリプトが実行されているCXoneクラスターのエイリアスを指定します。 例えば、 C7 や M33などです。
inContactScriptEngineHost 文字列 該当し、利用可能な場合は、 CXoneスクリプトエンジンのホスト名を指定します。 例えば、 lax-c4cor01やaoa-c32cor01などです。
consumerMetaData オブジェクト

APIコンシューマーに関する任意かつ拡張可能なデータです。

{
	< * >:

}

WebSocketHookInitializeMessage

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

パラメーター

タイプ

詳細
authenticationToken 文字列

のCustom Agent Assist EndpointsアプリAgent Assist Hubで設定した認証ヘッダーを含みます。
executionInfo   ActionExecutionInfoオブジェクトを含みます。
systemTelemetryData   SystemTelemetryDataオブジェクトを含みます。
streamPerspective   StreamPerspectiveの値を含みます。
streamsConfiguration   現在は使用されていません。
appParams  

Studioスクリプトや他のソースなどから渡すことができる動的なコンタクトパラメーターです。

{ parameters
}
appConfig  

事前に構成されたエージェントアシストアプリケーションの構成設定。

{ parameters
}