ストアリリース 3.0.x で利用可能な仮想エージェント API 機能
仮想エージェント API バージョン 3.0.x では、仮想エージェントおよびエージェントチャットで利用可能な同じ機能の多くにアクセスできます。これには、プライベート URL からファイルをアップロードする機能や同期ハンドシェイクの機能拡張などが含まれます。
コンテキストアクションとコマンドの変更
- ゲストユーザーは、コマンドを入力するときにアカウントのリンクを要求されなくなりました。
- ユーザーが会話の外で [キャンセル] または [いいえ] をクリックすると、仮想エージェントによってヘルプカードが表示されます。
- 会話の途中でユーザーが [キャンセル] または [いいえ] をクリックすると、仮想エージェントによって現在のトピックが再開され、[会話を再開しています] というメッセージが表示されます。
- ヘルプカードに、[さようなら] および [通知を表示] (有効な場合) コマンドが含まれるようになりました。
emailId が送信されない場合 (ユーザーがゲストの場合)、仮想エージェントにはアカウントをリンクするオプションが表示されません。
コンテキストアクションとコマンドの詳細については、「カスタムチャット統合のコンテキストアクション」を参照してください。
破棄された仮想エージェントの会話の終了
エラーが原因で会話が不完全な場合、仮想エージェントはプライマリボットに制御を依頼することができます。takeControl フラグが true の場合、仮想エージェントは (セカンダリボットとして) 会話を自動的に終了します。プライマリボットが会話を開始する場合、"hi"/START_CONVERSATION のアクションメッセージを送信できます。
- アイドルタイムアウト：インタラクションステータスが [破棄してクローズ] です。ステータスの理由は [アクティビティなし]です。
- 技術的な問題：インタラクションのステータスが [破棄してクローズ] です。ステータスの理由は [ボットの問題 (Bot issues)] です。
- 無効なユーザー入力：インタラクションステータスが [破棄してクローズ] です。ステータスの理由は [無効なユーザー入力 (Invalid user input)] です。
プライマリボットに制御を求めるには、ペイロードの本文にある takeControl フラグを true の値でプライマリボットに送信します。
{
"requestId": "xxxx-xxxx-xxxx-xxxx",
"clientSessionId": "xxx-xxx-xxx-xxx",
"message": {
"text":"invalid3",
"typed":true
}
"body":[{
"uiType":"OutputText",
"group":"DefaultText",
"value":"Sorry, I didn't get that. Could you help me by answering this?"
},
{
"uiType":"Boolean",
"group":"DefaultPicker",
"required":true,
"nluTextEnabled": false,
"label":"Choose a value",
"options":[
{"label":"Yes"},
{"label":"No"}
]
}],
"takeControl":true,
"score":0
} トピックの切り替えエラーとトラブルシューティングの改善
- 要求に、トピック名とトピック ID (キーワードトピック検出) またはトピックインテント名とトピックインテント ID (NLU トピック検出) の両方が含まれています。いずれか一方を指定します。
- 要求に無効なトピックかインテント名、または ID が含まれています。
- トピック/インテント名または ID は有効ですが、非アクティブであるかトピックでないため、仮想エージェントで実行できません。たとえば、名前または ID がトピックブロックまたはカスタムコントロールオブジェクトを参照している場合などです。
- 要求されたトピックが既に実行されています。
- 要求されたトピックは有効ですが、セキュリティ条件によりアクセスできません。たとえば、トピックの実行がチャネルで許可されていない場合や、その他のアクセス制御条件が適用されている場合などがあります。
- トピックの切り替えに失敗すると、会話を続行できないことを示すメッセージが表示されて会話が終了します。会話はオープンステータスのままではなくなります。
- 前の要求は処理済みとしてマークされるため、タイムアウトを待たずに新しい要求を行うことができます。
- 失敗の理由は、システムログテーブル ().
同期ハンドシェイクの機能拡張
バージョン 3.0.x 以降、仮想エージェント API はライブエージェントへの転送を同期的に行うことができます。ユーザーまたはエージェントが会話を終了すると、仮想エージェントへの転送も同期的に行われます。一部のシステムメッセージと待機時間メッセージも同期的に送信されます。
- 仮想エージェントの応答エンドポイントを構成します。エージェントチャットのメッセージは、指定したエンドポイントに配信されます。
- インスタンスの通知は手動でオフにする必要があります。
- ライブエージェントへの同期転送を使用している場合、仮想エージェント API は、入力インジケーターが有効になっている場合は送信します。
{ "uiType": "ActionMsg", "actionType": "StartTypingIndicator", } - 次の機能を使用するトピックは、同期モードではサポートされていません： ファイルアップロード、 アクション ユーティリティ、および一時停止トピックブロック。
- 移動先 .
- [ボット間 (Bot to Bot)] レコードを選択します。
- 無効にするには、[通知の有効化] チェックボックスをオフにします。
- 同期モードでライブエージェントへの転送を行わない場合は、[入力インジケーターをサポート] チェックボックスをオフにして無効にします。
- [同期] チェックボックスをオンにします。
図 : 1. 同期サポートを有効にしたボット間チャネル - [更新] をクリックします。
アクションメッセージのサポート
ServiceNow® 仮想エージェントのセカンダリボットにメッセージを渡すだけでなく、プライマリボットまたはチャットクライアントはエージェントチャットを介してエージェントにメッセージを渡すことができます。要求の本文で渡された action パラメーターを使用して、コンテンツの処理方法を指定します。
| actionType 値 | 説明 |
|---|---|
| ChatSubHeader | 次のいずれかが発生したことを示す送信メッセージ：
|
| StartSpinner | メッセージが AI 検索 や汚い言葉フィルターなどの非同期プロセスのために処理待ち状態になっているときにスピナーを開始する送信メッセージ。 |
| EndSpinner | 以前に送信されたスピナーを停止する送信メッセージ。 |
| StartTypingIndicatorActionMsg | (エージェントがチャットを受け入れた後に) ユーザーまたはエージェントが入力を開始したことを示す送信メッセージ。 |
| EndTypingIndicatorActionMsg | ユーザーまたはエージェントが入力を停止したことを示す送信メッセージ。 |
| SubscribeToSupportQueue | 会話がサポートキューに設定されていることを示します。 |
| SubscribeToChatPresence | ライブエージェント会話が開始されたことを示す送信メッセージ。 |
| SwitchToLiveAgent | ライブエージェントが会話を受け入れたことを示す送信メッセージ。 |
| SwitchToVirtualAgent | ライブエージェントセッションが終了し、会話が仮想エージェントに戻されたことを示す送信メッセージ。 |
| SwitchConversation | 通知が送信されたことを示す送信メッセージ。これにより新しい会話が作成されるため、仮想エージェントは新しい会話に切り替わります。 |
| System | 次のいずれかを示す送信メッセージ：
|
silentMessage フラグのサポート
サイレントメッセージは、応答を必要としないメッセージです。仮想エージェント が silentMessage=true の要求を受信した場合、仮想エージェント がサイレントモードをオフにする要求 (silentMessage=false) を受信するまで、その後のすべてのボットメッセージは非表示になります。
{
"token": "BOT_TOKEN",
"botToBot": true,
"clientSessionId": "884502214730301027f83ee4070f589a",
"clientVariables": {},
"requestId": "48450221d23030107300b7756770bc9b",
"silentMessage": "true",
"timestamp": 1623916324820,
"timezone": "GMT",
"userId": "abel.tuter",
"emailId": "abel.tuter@example.com"
}プライベート URL からの安全なファイルアップロード
- プロバイダーアプリケーション ID はオプションです。
- ユーザー ID とプロバイダーアプリケーション ID は、ペイロードのファイル名の前に送信する必要があります。
- エンドユーザーは、glide.attachment.role プロパティで指定されたロールを持っている必要があります。詳細については、「ファイルを添付するために必要なロール」を参照してください。
- 基本認証または OAuth 認証はサポートされていますが、メッセージ認証はサポートされていません。
curl -X POST \
https://instance.service-now.com/api/now/v1/cccif/media/upload \
-H 'authorization: Basic YWRtaW46YWRtaW4=' \
-H 'content-type: multipart/form-data; \
-F user_id=xxxxxx \
-F provider_application_id=optionalId \
-F 'file=@SomeFile.png'{
"result": {
"mediaUrl": "http://123.456.7.8:8080//api/now/v1/cs/media/string",
"name":"imagefile.png",
"state":"pending",
"attachmentId":"abcdefghijklmno12345"
}
}カスタム変換マップのサポート
開発者は、getTransformerMap メソッドを使用してカスタム変換マップを渡すことができます。カスタム変換マップを使用すると、デフォルトの変換ロジックを上書きできます。
/** Custom transformation map based on control types in DialogFlow messenger **/
getTransformationMap: function() {
return {
‘text’: ‘transformText’,
‘info’: ‘transformInfoCards2’,
‘description’: ‘transformDescription’,
‘button’: ‘transformButtonLink’,
‘image’: ‘transformImage’,
‘chips’: ‘transformChips’,
/* fallback logic in case VA API response format is mentioned in Dialogflow custom response payload */
‘servicenow’: ‘transformServiceNowResponse’
};
},
この例では、テキスト、情報、説明などはセカンダリボットに対応するコントロールタイプです。指定されたメソッド (transformText など) は、コントロールタイプの変換を行うために呼び出されます。セカンダリボット応答ごとに、仮想エージェント は getControlType メソッドを使用して、セカンダリボットメッセージの変換マップで指定されたコントロールタイプを返します。Google Dialogflow の受信トランスフォーマーは、これの使用方法の良い例を示します。
呼び出された変換メソッドが存在しない場合、仮想エージェント API はそれをエラーとして記録します。