Context handler function

La Context handler function se usa para controlar el flujo conversacional de una acción. Puedes cambiar el orden en que los params se solicitan a los usuarios en tiempo de ejecución. También puedes omitir algunos params, hacer validaciones personalizadas de los valores de los params, y también pedir una confirmación antes de la ejecución de la acción en tiempo de ejecución.

La Context handler function puede anular el orden en que se definen los params estáticos. Si la context handler function está habilitada, el bot solicitará los parámetros en el orden dictado por la context handler function y no por el orden que declaraste al definir los params en la consola de Catalyst.

Invocation Point

Una vez que ConvoKraft detecta la acción del input del usuario, se detectarán los posibles valores de params que están presentes en el input del usuario, luego el bot solicitará el primer param faltante al usuario. Cuando un usuario responde a la solicitud del param, ConvoKraft invocará la context handler function. La context handler function se invoca para cada param que se solicita en la conversación. Si una acción no tiene params, la context handler function se ejecutará una vez antes de la execution function.

Input Arguments

Además de los argumentos de entrada definidos por el sistema, los siguientes argumentos de entrada también están disponibles para la Context handler function:

Return Value

La Context handler function retorna un mapa en el siguiente formato:

{
"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>" //Añadir los datos del cliente según sea necesario
}	 
}
}

Como se muestra arriba, las siguientes claves pueden estar presentes en el mapa retornado por la Context handler function:

todo

Esta clave se usa para indicar qué debe hacer un bot de ConvoKraft después de la ejecución de la context handler function. Solo puede tomar uno de los siguientes valores. También, ten en cuenta que esta clave es obligatoria.

• prompt: Instruye al bot para solicitar un param al usuario.
• confirm: Instruye al bot para pedir una confirmación final para invocar la Execution function de la acción.
• execute: Instruye a ConvoKraft para invocar la Execution function.

prompt

Esta clave contiene un mapa que especifica qué param se debe solicitar al usuario y se usa solo si todo está establecido como prompt.

Si esta clave no se proporciona aunque todo esté establecido como prompt, el bot solicitará el siguiente param según el orden de los params definidos en la consola. Por lo tanto, esta clave puede omitirse si se debe usar el orden predeterminado de la definición de params. El valor de mapa de esta clave contiene los siguientes atributos:

1. param_name: El nombre del param a solicitar. El nombre del param debe ser uno de los params existentes definidos en la consola.

2. prompt_msg: Se puede usar para anular el mensaje de solicitud del param definido al crear el param en la consola de Catalyst.

   validation_failure_message: El mensaje personalizado a mostrar si el input dado por el usuario es inválido para el param solicitado. Esta clave es opcional.

3. options: La lista de opciones de los params de lista de selección única y múltiple, de las cuales el usuario puede hacer una elección.

• id: El ID único de la opción.
• label: El texto a mostrar como etiqueta de la opción.
• preview: La información adicional a mostrar para las opciones en los params de lista de selección única y múltiple. Las vistas previas de opciones estarán disponibles solo cuando el modo de entrada de los params de lista de selección única y múltiple sea Visual. La clave preview es opcional.
• header: El header lista las propiedades de las opciones de params de lista de selección única y múltiple. El objeto header debe contener los siguientes atributos en el formato que se muestra a continuación:

{
"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>"
}
}
}
}

Si el objeto header está configurado con estos atributos apropiados para las opciones, entonces la vista previa se mostrará cuando el usuario haga clic en el ícono de información en cada opción.

Cuando haces clic en el ícono de información, se mostrarán la imagen, el nombre y la URL configurados.

• fields: El objeto fields lista las propiedades adicionales sobre las opciones. El objeto fields debe contener los siguientes atributos en el formato que se muestra a continuación. Esto es obligatorio solo si se configura el preview.

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

Los elementos clave de la clave preview son, header y fields. Si el objeto fields está configurado junto con la clave preview, entonces las vistas previas apropiadas se mostrarán cuando el usuario pase el cursor sobre las opciones respectivas y no habrá ícono de información mostrado en este caso.

4. buttons: Los buttons se usan para configurar las operaciones a realizar sobre las opciones definidas en los params de lista de selección única y múltiple. La clave buttons debe contener los siguientes atributos en el formato que se muestra a continuación.

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

confirm

Esto contiene un Map que especifica el mensaje de confirmación para la ejecución de la acción que debe ser solicitado al usuario. Es obligatorio solo si todo está establecido como confirm. El valor del mapa solo puede contener la clave listada a continuación:

• message: El mensaje de confirmación que debe ser solicitado al usuario.

assign

El valor de la clave assign es de tipo Map. Se puede usar para cambiar los valores de todos los params estáticos y los argumentos definidos por el sistema en tiempo de ejecución.

• clientData: Se usa para actualizar los valores de datos del cliente basándose en los datos de sesión en tiempo de ejecución.

Implementación

Una vez que crees una acción para tu bot de ConvoKraft y elijas configurar la respuesta basada en una lógica de negocio, debes definir las oraciones de ejemplo y los params respectivos para ella. Asegúrate de seguir los pasos listados a continuación para implementar la Context handler function:

1. Después de configurar y guardar las oraciones de ejemplo y params requeridos para una acción, se mostrará la página de detalles de la acción. Cambia a la pestaña Functions y habilita la Context Handler function.

2. Se te mostrará el siguiente mensaje, haz clic en OK para continuar.

3. Se abrirá el editor de Deluge de ConvoKraft donde puedes codificar tu lógica de negocio y guardar el script. Obtén más información sobre el editor de Deluge en esta página. Puedes probar los cambios en paralelo usando la función Test this bot.