入力Transformer

説明

入力Transformerは、Flowが実行される前に、ユーザーからのすべてのメッセージに対してトリガーされます。これにより、Flowに送信される前のテキストを操作したり、外部システムと通信したり、新しいチャネルとの統合を実装したり、さまざまなことが可能になります。

入力Transformerは、EndpointのTransformerにhandleInput関数を実装することで構成されます。

Transformer関数の引数

handleInput関数は、設定オブジェクトを引数として受け取ります。このオブジェクトは常に、Endpoint設定を含むkey endpointを含んでいます。オブジェクト内の残りのキーはTransformerのベースタイプに異なります。オブジェクト内のキーの概要を以下に示します。

Transformerの戻り値

通常のTransformerの使用方法

入力Transformerは、有効なユーザーID、セッションID、およびFlowに送信されるべきテキストまたはデータを返すことができます。これらの値はリクエストボディから抽出されなければなりません。リクエストボディのフォーマットは、使用される特定のチャネルによって異なることに注意することが重要です。例えば、Alexaからのリクエストは、Facebook (Meta) Messengerからのリクエストと比較して、非常に異なるように見えます。リクエストボディの書式を知るためには、そのチャネルのドキュメントを読む必要があります。

例：

return {
    userId: request.body.user,
    sessionId: request.body.conversation,
    text: request.body.messageText,
    data: { "test": 1 }
};

部分的な Transformer の結果

ユーザー ID、セッション ID、テキスト、またはデータに対して undefined が返された場合、Endpointから既に抽出された値が使用されます。

以下の例では、textとdataは上書きされますが、userIdとsessionIdはそのまま保持されます：

実行の停止

入力Transformerが完全に不正な値を返す場合、ユーザーからのメッセージはけっしてFlowに送信されません。

例：

return null;

Transformersとトークのカウント

Cognigy.AIでのトークは、入力Transformerが不正でない結果を返した場合のみカウントされます。

Transformers とイベントメッセージ

Webchat と Socket.IOのEndpointは、ユーザーが接続中（user-connected）か切断中（user-disconnected）かなど、 ユーザーのアクティビティを示すイベントメッセージを生成します。これらのイベントメッセージは Flowをトリガーせず、カウントされませんが、入力Transformersを使用することで これらのイベントメッセージにアクセスする可能性があります：

{
    "userId": "<current-user-id>",
    "sessionId": "<current-session-id>",
    "text": "",
    "data": {
        "_cognigy": {
            "event": {
                "type": "user-connected"
            }
        }
    }
}

イベントメッセージはHandoverプロバイダにユーザのアクティビティを通知し、ヒューマンエージェントがユーザがまだトークに参加しているかどうかを判断できるようにします。

入力Transformersでこれらのイベントメッセージに気付いたら、変更せずにそのまま転送することをお勧めします。イベントメッセージは、そのデータペイロードが特定のフォーマットに従っている場合にのみ、そのように認識されます。この結果を得るには、入力Transformerで以下のコードスニペットを使用します：

{

    handleInput: async ({ payload, endpoint }) => {
        if (!!payload.data?._cognigy?.event) {
            // pass on "event messages" without modification
            return payload;
        }

        // rest of your input transformer code
    }
}