入力Transformer
説明
入力Transformer
は、Flowが実行される前に、ユーザーからのすべてのメッセージに対してトリガーされます。これにより、Flowに送信される前のテキストを操作したり、外部システムと通信したり、新しいチャネルとの統合を実装したり、さまざまなことが可能になります。
入力Transformer
は、EndpointのTransformerにhandleInput
関数を実装することで構成されます。
![](https://cognigy.tdse.jp/wp/wp-content/uploads/2024/02/7944f05-handleInputTransformer.png)
Transformer関数の引数
handleInput
関数は、設定オブジェクトを引数として受け取ります。このオブジェクトは常に、Endpoint設定を含むkey endpoint
を含んでいます。オブジェクト内の残りのキーはTransformerのベースタイプに異なります。オブジェクト内のキーの概要を以下に示します。
引数 | 説明 | Webhook Transformers | REST Transformers | Socket Transformers |
endpoint | Endpoint の設定オブジェクト。URLTokenなどが含まれます。 | X | X | X |
request | JSONをパースしたボディを持つ Expressリクエストオブジェクト。 | X | X | |
response | Expressレスポンスオブジェクト。 | X | X | |
payload | ペイロードオブジェクトには、ソケットを通して送信されたuserId、sessionId、テキスト、データが含まれます。また、クライアントのチャネルも含まれます。 | X |
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が不正でない結果を返した場合のみカウントされます。
戻り値の検証
入力Transformer
の戻り値が指定された場合、一連のルールに対して検証され、ルールが満たされない場合は拒否されます。すべての値はundefinedを返すことができます。それ以外の値が返される場合は、以下のルールが適用されます:
・ユーザー IDは最大256文字の文字列です。
・セッションIDは最大256文字の文字列です。
・テキストは最大10000文字の文字列です。
・データはオブジェクトです。
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
}
}