Hay tres tipos de funciones que actúan como hooks durante la ejecución de la acción:

• Ejecución de la acción (obligatorio): se invoca al final de una acción, después de haber llenado todos los parámetros.
• Cargador de params (opcional): se invoca después de que se haya llenado todos los params estáticos.
• Manipulador de contexto (opcional): se invoca por cada entrada del usuario durante el curso de una acción.

Flujo de ejecución de acción

Cuando un usuario ingresa una frase en Zia, el software intenta entender el texto ingresado por el usuario y comprueba si coincide con alguna de las acciones configuradas. Si coincide con alguna de las acciones configuradas, Zia pedirá al usuario los params necesarios para ejecutar una acción como una conversación. Por cada entrada del usuario, se invocará la función del manipulador de funciones. Después de que se haya llenado todos los params estáticos, se invocará una sola vez la función del cargador de parámetros.

Una vez configurados todos los params brindados por el usuario, Zia ejecuta la función de ejecución de acción y responde al usuario con el mensaje devuelto por dicha función.

Agregar una nueva acción

Puede agregar nuevas acciones mediante la pestaña de personalización. El área de personalización brinda un ambiente similar al entorno de pruebas en el que puede desarrollar y probar nuevas acciones. En los siguientes puntos se explican los pasos necesarios para agregar nuevas acciones.

Para agregar una nueva acción:

1. Haga clic en Agregar campo.
2. Ingrese un nombre de acción.
3. En función de la acción prevista, elija si la acción debe contestar una pregunta o realizar una operación.
4. Si su acción responde a una pregunta, seleccione si la respuesta se debe proporcionar directamente o si la respuesta se debe crear a partir de CRM.
5. Defina las frases de ejemplo y los parámetros.
6. Haga clic en Siguiente.
   
7. De ser necesario, configure las funciones del cargador de params y del manipulador de contexto.
8. Haga clic en Editar código de ejecución.
9. Defina la función de ejecución.
10. Haga clic en Listo.
    Se creará la acción prevista y estará disponible en el chat de Zia solo cuando se haya publicado.

Definir las frases de ejemplo

Definir las frases de ejemplo es fundamental para determinar sus acciones, ya que estas son las frases que es probable que el usuario diga a Zia para generar una acción. Veamos algunas frases de ejemplo:

• Para las acciones que realizan operaciones, se deben definir las frases de ejemplo en la sección "¿Cómo se invocará esta operación?".
• Para las acciones que responden preguntas, se deben definir las frases de ejemplo en la sección "¿Cómo se puede responder a esta pregunta?".
• El texto ingresado como una frase de ejemplo se puede seleccionar y marcar como un param. Cuando seleccione el texto, aparecerá una ventana emergente que le permitirá asociar un param con el texto seleccionado o crear un nuevo param para asociarlo con el texto.

Puede agregar más frases de ejemplo haciendo clic en el ícono "+" y quitar frases concretas haciendo clic en el ícono "-".

También puede reordenar estas frases para que las más utilizadas aparezcan en la parte superior utilizando el ícono para reordenar que está al lado del cuadro de texto de frases de ejemplo.

Las tres primeras frases de ejemplo que el usuario agregue se mostrarán como una sugerencia para invocar una acción. Por lo tanto, se recomienda utilizar frases características que sean fáciles de recordar.

Definir los parámetros

Los params son datos ingresados por el usuario para completar una acción. Puede agregar un nuevo param para la acción haciendo clic en la opción "Nuevo" desde la lista de params o desde el cuadro de diálogo de sugerencias de params que aparece cuando marca params en las frases de ejemplo.

En la ventana emergente de nuevos params, ingrese la siguiente información:

Tenga en cuenta que el usuario puede proporcionar valores a todos estos tipos de datos en español, y que Zia convertirá la frase literal en el tipo de datos declarado.

1. Nombre de param: se debe proporcionar un nombre válido para el param, el que debe cumplir los siguientes requisitos:
   • Debe comenzar con una letra minúscula.
   • Solo puede incluir caracteres alfabéticos, numéricos y guiones bajo.
   • Debe ser para una única acción.
   • Está prohibido utilizar las siguientes palabras como nombre de param, ya que son palabras reservadas de Zia (userInput, previousParam, additionalParams, sessionData, broadcast, previousUserMsgs, cache, org y user).
2. Tipo de param: seleccione un tipo de datos apropiado para su param. Zia admite los siguientes tipos de datos:
   • Texto: cadenas
   • Número: números válidos.
   • Hora: horas válidas
   • Fecha: fechas válidas
   • Arreglo de selección única: una lista de las opciones disponibles a partir de la cual el usuario debe seleccionar una.
   • Arreglo de selección múltiple: una lista de las opciones disponibles a partir de la cual el usuario debe seleccionar más de una.
3. Params de tipo arreglo: si desea utilizar params de tipo arreglo, es posible que deba ingresar la siguiente información adicional:
   • Valores de arreglo: puede incluir una lista de opciones a partir de la cual el usuario puede seleccionar una o varias. De forma alternativa, puede ingresar el ID de cada opción o utilizar el ID generado automáticamente mientras escribe solo los valores.
   • Modo de entrada: especifica la forma en que un param de arreglo solicita la información al usuario. Puede ser textual o visual. Si selecciona "textual", el usuario podrá escribir (si se trata del chat) o decir (si es por voz) el valor que desea asignar al param de arreglo. En caso de que seleccione el modo de ingreso "visual", el usuario tendrá que hacer clic o tocar la pantalla para seleccionar los valores del arreglo, los que se mostrarán como un botón de selección (en caso de solo una selección) o una casilla de verificación (en caso de varias selecciones).
     
4. Mensaje de solicitud: es la pregunta que Zia realizará al usuario para que ingrese el valor del param como parte de la conversación que sostiene con el usuario. Por ejemplo, para obtener el valor del param "hora de inicio" de la acción de creación de un evento, se debería configurar el mensaje de solicitud como "¿A qué hora empieza el evento?" o "¿En qué momento se da inicio al evento?". Como alternativa, puede anular el mensaje de solicitud de un param con la función del manipulador de contexto.

Reordenación de los params: el flujo de conversación de Zia depende del orden de los params definidos. Una vez que se haya detectado una acción, Zia solicitará todos los params, uno por uno, mediante el mensaje de solicitud respectivo en el orden en que estén definidos. Para reorganizar los params, incluso después de su creación, basta con que los arrastre y suelte en la ubicación deseada.

Definir las funciones

Las funciones definidas para una acción en particular determinan el flujo de la conversación y la ejecución de la acción. Las funciones son hooks personalizados escritos por desarrolladores de acciones que son invocadas por Zia durante el curso de una acción de ejecución en los puntos de invocación adecuados.

Todas las acciones se deben escribir en Deluge. Deluge es un lenguaje de programación en línea para el ambiente de desarrollo en la nube de Zoho. Consulte esta guía para obtener información detallada sobre Deluge.

Hay tres funciones que actúan como hooks durante la ejecución de Zia. Zia invocará estas funciones en los puntos de invocación apropiados con los valores exactos de todos los argumentos. Todas las funciones definidas deben devolver el valor del tipo de datos especificado.

Los siguientes argumentos de entrada definidos por el sistema están disponibles para todas las funciones, además de los argumentos de la función específica.

Además de los argumentos definidos por el sistema anteriormente mencionados, también estarán disponibles en forma de argumentos para cada función todos los params estáticos definidos para la acción. Cada parámetro estático es por sí mismo un argumento para cada función.

Zia llenará los valores pertinentes de todas las variables y los pasará como argumentos para todas las funciones.

Cada función tiene su propia especificación de datos de retorno. Tenga en cuenta que es responsabilidad del desarrollador cumplir el contrato de datos de retorno para el buen funcionamiento de su acción.

Definir la función del cargador de params

La función del cargador de params se utiliza para agregar nuevos parámetros a la acción de manera dinámica durante su ejecución, en forma de params adicionales a los parámetros estáticos ya definidos. Esta función resulta útil cuando no conocemos con anticipación los params de una acción, lo que generalmente sucede cuando los params cambian según el usuario. La definición de la función del cargador de params es opcional.

Por ejemplo, si vamos a escribir una acción para crear una tarea dentro de CRM, el formulario de creación de tareas será diferente para cada usuario según su configuración de diseño. En tales casos, debemos cargar los campos del formulario de creación de tareas como params dinámicos a través de la función del cargador de params, de modo que Zia pueda solicitar dichos parámetros, uno por uno, para crear una tarea.

Tenga en cuenta que Zia no podrá detectar los valores de los parámetros dinámicos que se carguen por medio de la función del cargador de params y que se podrían haber mencionado en la frase de invocación. Zia solo solicitará los params dinámicos uno por uno mediante el mensaje de solicitud determinado para cada uno de ellos en la función del cargador de params.

Punto de invocación

Una vez que Zia detecte la acción en la información ingresada por el usuario, también detectará los valores de param estático presentes. Los params estáticos faltantes se solicitarán al usuario uno por uno en el mismo orden en que se los definió. Una vez que todos los params estáticos estén llenos, Zia invocará la función del cargador de params con los valores pertinentes de todos los argumentos de ingreso.

Si no hay params estáticos definidos, la función del cargador de params se invocará cuando Zia detecte una acción. La función del cargador de params se invocará solo una vez durante el ciclo de ejecución de una acción.

Argumentos de ingreso

Además de los argumentos definidos por el sistema, también están disponibles los siguientes argumentos para la función del cargador params.

Valor de retorno

La función del valor de retorno debe devolver un mapa con el siguiente formato:

additionalParams (obligatorio): el valor de esta clave debe ser una lista de params. Cada parámetro debe ser del tipo de datos "mapa". Las siguientes son las propiedades de un objeto de mapa de param.

1. name: nombre del param.
2. data type: tipo de datos del param. Esta propiedad puede tomar uno de los siguientes valores.
   • text
   • number
   • date
   • time
   • boolean
   • array_checkbox
   • array_radio
3. prompt_msg: el mensaje de solicitud del param.
4. options: las opciones de un param tipo arreglo como lista. Cada opción es un mapa que tiene las claves "id" y "label".
5. input_mode: el modo de ingreso de un param tipo arreglo. El valor puede ser TEXTUAL o VISUAL.
   Obligatorio: dichas claves deben estar presentes en el mapa del param.
6. assign (opcional): el valor de esta clave debe ser un mapa. Esta clave se utiliza para cambiar los valores a los argumentos de ingreso modificables de la función. Todos los params estáticos y argumentos caché definidos por el sistema son modificables.

Definir la función del manipulador de contexto (opcional)

La función del manipulador de contexto se utiliza para controlar el flujo de conversación de una acción. Puede cambiar el orden en el que se solicitan los params a los usuarios durante la ejecución. También puede saltarse algunos params, hacer validaciones personalizadas de los valores de los param y solicitar una confirmación antes de realizar la acción durante el tiempo de ejecución.

Tenga en cuenta que la función del manipulador de contexto puede anular el orden en que se definieron los params estáticos. Si la función del manipulador de contexto está habilitada, Zia solicitará los parámetros en el orden dictado por este y no por el orden que el usuario declaró cuando definió los parámetros.

Punto de invocación

Una vez que Zia detecte la acción de la información ingresada por el usuario, se detectarán los posibles valores de param estático presentes ingresados por el usuario. Posteriormente, Zia solicitará al usuario el primer param estático faltante. Cuando un usuario responda a la solicitud de param, Zia invocará la función del manipulador de contexto. De esta forma, se invoca la función del manipulador de contexto para cada param que se solicita en la conversación. Esto sucede tanto para los params estáticos como para los dinámicos. Si una acción no tiene ningún param, la función del manipulador de contexto se ejecutará una vez antes de la función de ejecución.

Argumentos de ingreso

Además de los argumentos definidos por el sistema, también están disponibles los siguientes argumentos para la función del manipulador de contexto.

Valor de retorno

La función del cargador de param debe retornar un mapa con el siguiente formato:

todo (obligatorio): se utiliza para indicar a Zia lo que debe hacer después de completar la función del manipulador de contexto. Esta clave debe estar presente en la respuesta de la función del manipulador de contexto. Puede tomar uno de los siguientes valores:

1. prompt: ordena a Zia que solicite un param al usuario.
2. confirm: ordena a Zia que pida una confirmación definitiva para invocar la función de ejecución de la acción.
3. execute: ordena a Zia que invoque la función de ejecución de la acción.

prompt (solo aplica si "todo" = "prompt"): contiene un mapa que especifica los parámetros que se deben solicitar al usuario. Si no se brinda esta clave, ni siquiera cuando "todo" está configurado como "prompt", Zia solicitará el param siguiente según el orden que se definieron los params. Se deberá omitir esta clave si se debe utilizar el orden predeterminado de definición de los params. El valor del mapa puede contener las siguientes claves:

1. param_name *: el nombre del param que se debe solicitar. El nombre del param debe ser uno de los params estáticos o dinámicos declarados.
2. options: las opciones que se mostrarán como params de sugerencia. Se aplica solo a los params de tipo arreglo.
3. msg: se utiliza para anular momentáneamente el mensaje de solicitud predeterminado del param.

confirm (obligatorio solo si "todo" = "confirm"): contiene un mapa que especifica el mensaje de confirmación, para la ejecución de la acción, que se debería mostrar al usuario. El valor del mapa puede contener las siguientes claves:

1. message: el mensaje de confirmación que se debe mostrar al usuario.

assign: el valor de esta clave debe ser un mapa. Esta clave se utiliza para cambiar los valores a los argumentos de ingreso modificables de la función. Todos los params estáticos y argumentos caché definidos por el sistema son modificables.

Función de ejecución

La función de ejecución es el punto final de la ejecución de una acción. Define la finalización de una acción. Es la ejecución misma de la acción y brinda un mensaje de finalización exitosa (o de fallo) al usuario, como resultado de la finalización de una acción. La respuesta brindada al usuario puede ser un texto o una colección de cartas (elementos visuales).

Punto de invocación

La función de ejecución se invoca en el punto final de una acción. Por defecto, el punto final de una acción viene después de haber solicitado todos los param y que se hayan llenado con los valores apropiados. De forma alternativa, el punto final también se puede definir de la función del manipulador de contexto ("todo" : "execute"). Una vez que se invoque la función de ejecución, se completará la acción y cualquier otra conversación del usuario se considerará como una nueva acción.

Argumentos de ingreso

Además de los argumentos definidos por el sistema, también están disponibles los siguientes argumentos para la función de ejecución.

Valor de retorno

La función de ejecución debe retornar un mapa con el siguiente formato:

message (obligatorio): para brindar un texto como respuesta al usuario. El texto se procesará a través de voz o texto, lo que dependerá del medio de comunicación.

tarjeta (obligatorio): para brindar un mensaje en formato visual como respuesta al usuario. Una tarjeta es una colección de elementos visuales, como una tabla, imagen, etc. La tarjeta se mostrará en pantalla tanto para las llamadas como para las interacciones por medio del chat. El valor de esta clave es una lista de los objetos del mapa. Cada objeto del mapa representa un elemento de interfaz de usuario de la tarjeta. Una sola tarjeta puede contener más de un elemento del mismo tipo. En el mensaje de respuesta, se mostrarán los elementos de la tarjeta en forma de lista.

A continuación, está la lista de los elementos de la IU admitidos por Zia:

Publicar una acción

Las acciones personalizadas se escriben en el entorno de pruebas y no estarán disponibles para el resto de los usuarios de la organización. Para que todos los usuarios puedan utilizar las acciones personalizadas, los datos de la acción se deben actualizar a Zia.

Para actualizar todas las acciones escritas para Zoho CRM, haga clic en el botón "Actualizar" que está en la pestaña de Zoho CRM. Tenga en cuenta que el botón de actualización solo será visible si existen actualizaciones disponibles para las acciones personalizadas que ha escrito.

Permisos en Zia

El administrador de Zia puede proporcionar los controles de acceso a los usuarios según su nivel de jerarquía y función dentro de la organización. La siguiente lista muestra los niveles de permisos para cada función.

1. Usuario: solo puede chatear o hablar con Zia.
2. Desarrollador: puede escribir habilidades para Zia.
3. Gestor: puede actualizar las habilidades para Zia con el fin de que estén disponibles para todos los usuarios.
4. Administrador: puede administrar a otros usuarios.
5. Superadministrador: es el administrador principal.

Se debe tener como mínimo la función de desarrollador para poder acceder a la consola para desarrolladores. Los usuarios con función de administrador tienen el permiso para modificar las funciones de los otros usuarios. Podrán encontrar la opción para modificar la función de los usuarios en la pestaña de ajustes. En Ajustes, haga clic en el usuario cuya función desea cambiar. Haga clic en la opción "Cambiar función", elija una nueva función para el usuario desde la lista desplegables y haga clic en "Actualizar". El usuario se moverá a la nueva función.