Context Handler関数

Context Handler関数は、Actionの会話フローを制御するために使用されます。実行時にparamがユーザーにプロンプトされる順序を変更できます。一部のparamをスキップしたり、param値のカスタムバリデーションを行ったり、実行時にAction実行前に確認を求めたりすることもできます。

Context Handler関数は、静的paramが定義されている順序をオーバーライドできます。Context Handler関数が有効な場合、BotはCatalystコンソールでparamを定義した際に宣言した順序ではなく、Context Handler関数で指定された順序でパラメータをプロンプトします。

呼び出しポイント

ConvoKraftがユーザー入力のActionを検出すると、ユーザー入力に含まれる可能なparam値が検出され、Botは最初の未入力paramをユーザーにプロンプトします。ユーザーがparamプロンプトに返信すると、ConvoKraftはContext Handler関数を呼び出します。Context Handler関数は、会話中にプロンプトされるすべてのparamに対して呼び出されます。Actionにparamがない場合、Context Handler関数はExecution関数の前に1回実行されます。

入力引数

システム定義入力引数に加えて、Context Handler関数では以下の入力引数も利用可能です：

戻り値

Context Handler関数は、以下の形式のマップを返します：

{
"todo":"prompt",
"prompt":{
"param_name":"<name of the param to be prompted>",
"prompt_msg":"<the text to be displayed as a prompt message>",
"validation_failure_message":"<the text to be displayed if the user submits invalid input>",
"options":[ ],
"buttons":[ ],
"fields":[ ], 
},
"confirm":{
"message":"Are you sure you want to cancel?"
},
"assign":{
"clientData":{
"<key1>":"<value1>",
"<key2>":"<value2>" //必要に応じてクライアントデータを追加する
}	 
}
}

上記のように、Context Handler関数から返されるマップには以下のキーが含まれます：

todo

このキーは、Context Handler関数の実行後にConvoKraft Botが何をすべきかを示すために使用されます。以下の値のいずれかのみを取ることができます。このキーは必須です。

• prompt：ユーザーにparamをプロンプトするようBotに指示します。
• confirm：ActionのExecution関数を呼び出すための最終確認を求めるようBotに指示します。
• execute：Execution関数を呼び出すようConvoKraftに指示します。

prompt

このキーには、ユーザーにプロンプトするparamを指定するマップが含まれ、todoがpromptに設定されている場合にのみ使用されます。

todoがpromptに設定されていてもこのキーが提供されない場合、Botはコンソールで定義されたparamの順序に従って次のparamをプロンプトします。したがって、param定義のデフォルト順序を使用する場合、このキーはスキップできます。このキーのマップ値には以下の属性が含まれます：

1. param_name：プロンプトするparamの名前。param名は、コンソールで定義された既存のparamのいずれかである必要があります。

2. prompt_msg：Catalystコンソールでparam作成時に定義されたparamのプロンプトメッセージをオーバーライドするために使用できます。

   validation_failure_message - プロンプトされたparamに対してユーザーが入力した値が無効な場合に表示されるカスタムメッセージ。このキーは任意です。

3. options：ユーザーが選択できるSingle selection listおよびMultiple selection list paramのオプションリスト。

• id：オプションの一意のID。
• label：オプションのラベルとして表示されるテキスト。
• preview：Single selection listおよびMultiple selection list paramのオプションに表示される追加情報。オプションプレビューは、Single selection listおよびMultiple selection list paramの入力モードがVisualの場合にのみ利用可能です。previewキーは任意です。
• header：headerは、Single selection listおよびMultiple selection list paramオプションのプロパティをリストします。headerオブジェクトには、以下の形式で以下の属性を含める必要があります：

{
"id":"<the unique id for the option>",
"label":"<the text to be displayed as the options label>",
"preview":{
"header":{
"title":"<the text to be displayed as the option previews title>",
"description":"<the text to be displayed as the option previews description>",
"subheading":"<the text to be displayed as the subheading to the options preview>",
"image":{
"url":"<the url of the preview image>"
}
}
}
}

headerオブジェクトにオプションの適切な属性が設定されている場合、ユーザーが各オプションの情報アイコンをクリックするとプレビューが表示されます。

情報アイコンをクリックすると、設定された画像、名前、URLが表示されます。

• fields：fieldsオブジェクトは、オプションに関する追加プロパティをリストします。fieldsオブジェクトには、以下の形式で以下の属性を含める必要があります。これは、プレビューが設定されている場合にのみ必須です。

[
{
"label":"<the text to be displayed as the field name>",
"value":"<the text to be displayed as the field value>"
}
]

previewキーのキー要素は、headerとfieldsです。fieldsオブジェクトがpreviewキーとともに設定されている場合、ユーザーがそれぞれのオプションにホバーすると適切なプレビューが表示され、この場合は情報アイコンは表示されません。

4. buttons：ボタンは、Single selection listおよびMultiple selection list paramで定義されたオプションに対して実行される操作を設定するために使用されます。buttonsキーには、以下の形式で以下の属性を含める必要があります。

[
{
"id":"the unique id for the button",
"label":"the text to be displayed as the button's label",
"theme":"<positive | neutral | negative>"
}
]

confirm

Action実行の確認メッセージを指定するマップが含まれ、ユーザーにプロンプトされます。todoがconfirmに設定されている場合にのみ必須です。マップ値には以下のキーのみ含めることができます：

• message：ユーザーにプロンプトする確認メッセージ。

assign

assignキーの値はMap型です。実行時にすべての静的paramとシステム定義引数の値を変更するために使用できます。

• clientData：実行時にセッションデータに基づいてクライアントデータの値を更新するために使用されます。

実装

ConvoKraft BotのActionを作成し、Business Logicに基づいて応答を設定することを選択したら、Sample Sentencesとそれぞれのparamを定義する必要があります。Context Handler関数を実装するには、以下の手順に従ってください：

1. Actionに必要なSample Sentencesとparamを設定して保存した後、Actionの詳細ページが表示されます。Functionsタブに切り替え、Context Handler functionを有効にします。

2. 以下のメッセージが表示されます。OKをクリックして続行します。

3. ConvoKraft Delugeエディタが開き、Business Logicをコーディングしてスクリプトを保存できます。Delugeエディタの詳細については、こちらのページをご覧ください。Test this bot機能を使用して、変更を並行してテストできます。