要求外のアクション 要求外のアクション

要求外のアクション

最終更新日:

要求外のアクション概要 | Unsolicited responses overview

英文ドキュメントではUnsolicited Responses(未承諾応答)と表現されていますが、日本語版では要求外のアクションとします。

要求外のアクションとは、エンドユーザーから直接の要求なしにデジタルヒューマンが話すアクション、つまり、ユーザーからデジタルヒューマンへ質問されていない場合に話をさせるアクションです。

デジタルヒューマンがアイドル状態の場合にのみ、一方的な応答をします。

ユーザーが質問しているときや、デジタルヒューマンが話しているときには利用出来ません。

UneeQのプラットフォームには、この種の応答プッシュモデルを可能にするAPIがあります。お客様のJWTシークレットに基づいて認証され、SDKからはアクセスできません。

要求外のアクションの送信 | Sending an unsolicited response

デジタルヒューマンを喋らせる為には、HTTP POSTリクエストで応答と指示をUneeQサーバーに送ることができます。

リクエストの仕様 | Request specification

Digital Humanに一方的な応答をさせるために、POST要求が以下の要求形式を使用して/api/v1/avatar/${sessionId}/speakに送信されます。

ヘッダー | Headers

Key

Value

Content-Type

application/json

パスバリアブル | Path variable

Field Type Description
sessionId String 現在の会話のカスタマーセッションID

ボディ | Body

このペイロードは、文字列化されたJSONである必要があります。

Field Type Description
answer String デジタルヒューマンが話すように設定したテキスト
answerAvatar String デジタルヒューマンの指示を含む文字列化されたJSON
sessionIdJwt String 顧客セッションIDは、顧客JWT secretを使用して暗号化。

 

セッションIDJWT | SessionIdJWT

これは、次のJSONを顧客のJWTシークレットで暗号化することによって取得されます。

{"sessionId":"<customer-session-id>"}

 

▼以下は、2つの異なる方法でsessionIdJWTを生成するサンプルJavaScriptコードです。

Install jsonwebtoken package https://www.npmjs.com/package/jsonwebtoken

   npm install jsonwebtoken

デフォルトの同期サイン (HMAC SHA256)

var jwt = require('jsonwebtoken'); 
var token = jwt.sign({ sessionId: '<customer-session-id>' }, '<customer-JWT-secret>');

▼外部ライブラリを使用せずにエンコードする

function base64url(source) {
// Encode in classical base64
encodedSource = CryptoJS.enc.Base64.stringify(source);

// Remove padding equal characters
encodedSource = encodedSource.replace(/=+$/, '');

// Replace characters according to base64url specifications
encodedSource = encodedSource.replace(/\+/g, '-');
encodedSource = encodedSource.replace(/\//g, '_');

return encodedSource;
}

var header = {
"typ": "JWT",
"alg": "HS256"
};

var data = {
"sessionId": "<customer-session-id>"
};

var secret = "<customer-JWT-secret>";

// encode header
var stringifiedHeader = CryptoJS.enc.Utf8.parse(JSON.stringify(header));
var encodedHeader = base64url(stringifiedHeader);

// encode data
var stringifiedData = CryptoJS.enc.Utf8.parse(JSON.stringify(data));
var encodedData = base64url(stringifiedData);

// build token
var token = encodedHeader + "." + encodedData;

// sign token
var signature = CryptoJS.HmacSHA256(token, secret);
signature = base64url(signature);
var signedToken = token + "." + signature;


const payload = JSON.stringify({
answer: "Is it there anything else I can help you with?",
answerAvatar: JSON.stringify({"instructions": {
"expressionEvent": [
{
"start": 0.1,
"value": 1,
"duration": 3,
"expression": "browsUpDown"
},
{
"start": 3,
"value": -1,
"duration": 3,
"expression": "browsUpDown"
}
]
}}),
sessionIdJwt: signedToken
});

応答フォーマット仕様 | Response format specification

応答は、コンテンツタイプがapplication/ jsonのJSONになります。

Code Status Response Reason
204 No Content  

非送信請求応答が正常に送信されました

400 Bad Request { "error": ERROR_DESCRIPTION }

リクエストの本文/ヘッダーが無効です

401 Unauthorized { "error": ERROR_DESCRIPTION }

sessionIdJWTが無効です

403 Forbidden { "error": ERROR_DESCRIPTION }

承認に失敗しました

406 Not Acceptable { "error": Avatar response queue limit reached }

5つの既存のメッセージがまだ配信されていないときにメッセージの発言が要求されました

500 Server Error { "error": ERROR_DESCRIPTION } サーバーでエラーが発生しました

 

レスポンスリミットの説明 | Response limit explained

 現在のところ、API は一度にキューに入れるメッセージの数を最大 5 個まで受け付けています。
5 つ以上のメッセージの発話を要求された場合、既存のメッセージが削除されるまで、つまりデジタルヒューマンによって完全に発話されるまで、API は 406 Not Acceptable を返します。

セキュリティー | Security

このAPIは、顧客のJWTSecretを使用し、ペイロードにセッションIDが署名されていることを確認することで保護されます。これにより、リクエストが有効なクライアントからのものであることを確認できます。

このAPIは、フロントエンドアプリではなく、常にバックエンドサービスによって動かされる必要があります