すべてのカテゴリ
開発・設置
要求外のアクション - スピーチAPI

要求外のアクション - スピーチAPI

要求外のアクション概要

🇯🇵 🇺🇸英文ドキュメントではUnsolicited Responses（未承諾応答）と表現されていますが、日本語版では要求外のアクションあるいはスピーチAPIと表現します。

 

要求外のアクション（スピーチAPI）とは、エンドユーザーから質問などの発話要求なしにデジタルヒューマンが話すアクションを指します。デジタルヒューマンがアイドル状態の場合に、あなたの意思で一方的に話しかけたり、任意のタイミングで発話指示をすることができます。

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

 
⚠️
要求外のアクションあるいはスピーチAPIはお客様のJWTシークレットに基づいて認証され、SDKからはアクセスできません。 このドキュメントは独自でオーケストレーションレイヤーを実装した場合に参照してください。デジタルヒューマン株式会社が提供するオーケストレーションレイヤーを使用している場合はこちらをご覧下さい。

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

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

 

リクエストの仕様

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

 

ヘッダー

Key
Value
Content-Type
application/json
 

パスバリアブル

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

ボディ

このペイロードは、文字列化された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
});
 

応答フォーマット仕様

応答は、コンテンツタイプが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 }
サーバーでエラーが発生しました

レスポンスリミットの説明

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

セキュリティ

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

このAPIは、フロントエンドアプリではなく、常にバックエンドサービスで実行する必要があります。

 
 
 
お役に立ちましたか？
😞
😐
🤩

最終更新日 January 1, 2023

チャットボット/NLP （自然言語処理）プラットフォーム統合の概要 デジタルヒューマンを試してみたい（デモと2週間の無料試用が可能です）