Controladores de estado

Organízate con las colecciones Guarda y clasifica el contenido según tus preferencias.
Los controladores de estado, también llamados simplemente controladores, se usan para controlar la conversación mediante la creación de respuestas a usuarios finales o la transición de la página actual. Para cada turno de conversación, los controladores se evalúan y pueden afectar la sesión. Los controladores tienen tres tipos generales de datos:

Término Definición
Requisitos del controlador Estos son los requisitos que se deben cumplir para que el controlador tenga efecto en la sesión. Se dice que un controlador se llama cuando se cumplen sus requisitos y afecta la sesión de alguna manera.
Entrega del controlador Si se llama a un controlador, se usa una entrega opcional a fin de crear respuestas para los usuarios finales. Estas respuestas se definen en datos del agente estático o se recuperan de forma dinámica desde tu servicio de webhook.
Objetivo de transición del controlador Si se llama a un controlador, se usa un objetivo de transición opcional para cambiar la página actual. La página siguiente solo puede ser una página de inicio de flujo o una página dentro del flujo activo actual.

Existen dos tipos de controladores de estado con requisitos de controlador diferentes:

Término Definición
Rutas Se llama a las rutas cuando una entrada de usuario final coincide con un intent o se cumple alguna condición en el estado de la sesión. Una ruta con un requisito de intent también se denomina una ruta de intents. Una ruta con solo un requisito de condición también se denomina una ruta de condición.
Controladores de eventos Los controladores de eventos se llaman cuando se invoca un evento. Algunos eventos integrados se activan cuando se recibe una entrada del usuario final inesperada o cuando se produce un error de webhook. También puedes definir eventos personalizados que invocas cuando algo sucede fuera de la conversación.

El procesamiento de un controlador de estado consta de tres pasos:

Término Definición
1. Scope Un controlador debe estar dentro del alcance para tener algún efecto en la sesión. El alcance se determina en función de si un controlador se aplica a un flujo, a una página o a un parámetro de formulario, y de si el flujo asociado está activo, la página asociada está activa o el agente intenta completar el parámetro del formulario asociado.
2. Evaluation Cada controlador dentro del alcance se evalúa en orden. Si se cumplen los requisitos de un controlador, se aprueba la evaluación.
3. Llamar Si un controlador está dentro del alcance y pasa la evaluación, se llama. Se llama a cualquier entrega asociada y se aplica cualquier objetivo de transición asociado a la sesión.

Alcance

Para que se evalúe un controlador, debe estar dentro del alcance. El alcance del controlador es una herramienta importante y potente que te ayuda a controlar la conversación. Si controlas el alcance de un controlador, puedes controlar lo siguiente:

X Elemento
Cuando un intent puede coincidir
Cuando se debe verificar una condición
Cuando se puede controlar un evento determinado
Cuando se puede realizar una transición de página
Cuando se proporciona una respuesta de entrega estática
Cuando se llama a una entrega habilitada para webhook para respuestas dinámicas

El alcance se determina en función de si un controlador se aplica a un flujo, a una página o a un parámetro de formulario, y de si el flujo asociado está activo, la página asociada está activa o el agente intenta completar el parámetro del formulario asociado.

Las reglas de alcance detalladas son las siguientes:

  • Rutas que se aplican al flujo activo:
    • Si la página actual es la página de inicio del flujo, están dentro del alcance.
    • Si la página actual no es la página de inicio del flujo, solo están dentro del alcance si tienen un requisito de intent.
  • Las rutas aplicadas a la página actual están dentro del alcance.
  • Los controladores de eventos aplicados al flujo activo están dentro del alcance.
  • Los controladores de eventos aplicados a la página actual están dentro del alcance.
  • Los controladores de eventos aplicados a un parámetro de formulario que el agente, en este momento, intenta completar están dentro del alcance.

Rutas

Las rutas tienen dos requisitos y se debe proporcionar uno o ambos. Si se proporcionan ambos requisitos, se deben cumplir ambos para llamar a la ruta:

Término Definición
Requisito de intent Un intent que debe coincidir con la entrada del usuario final para el turno de conversación actual. Cuando una ruta tiene un requisito de intent, se denomina ruta de intents.
Requisito de condición Una condición que se debe cumplir. Cuando una ruta tiene un requisito de condición, se denomina ruta de condición.

Puedes aplicar rutas a flujos (rutas a nivel de flujo) y a páginas (rutas a nivel de página). Por ejemplo, puedes usar rutas en las siguientes situaciones:

X Elemento
Cuando la entrada del usuario final coincide con un intent, la coincidencia debe activar una respuesta de entrega estática.
Cuando la entrada del usuario final coincide con un intent, la coincidencia debe activar una entrega habilitada para webhook para una respuesta dinámica.
Cuando la entrada del usuario final proporciona el parámetro de forma final requerido, una verificación de condición activa una transición de sesión a otra página.
Cuando la entrada del usuario final proporciona un parámetro de formulario específico, una verificación de condición activa una respuesta de entrega estática.
Es una verificación de condición configurada como true que fuerza una transición de página.

Propagación del intent

Por lo general, cuando se llama a una ruta debido a una coincidencia de un intent, el intent se consume. Un intent consumido no puede volver a coincidir, a menos que una entrada de usuario final nueva active una coincidencia de intent nueva. Sin embargo, es posible propagar una coincidencia de intent de un flujo a otro en la siguiente situación:

  • Una ruta en flow F1 tiene intent I1 como requisito y flow F2 como objetivo de transición.
  • Flow F2 tiene una ruta que también tiene intent I1 como requisito.

En este caso, cuando se llama a la ruta en flow F1, intent I1 coincide dos veces para una sola entrada del usuario final y se llama a ambas rutas.

La propagación de intents es útil para las siguientes tareas:

X Item
Cambia la página actual a una página específica en otro flujo (la ruta del flujo del destino de transición tiene una página de destino de transición específica).
Crea un mensaje de entrada para la página de inicio de un flujo (la ruta del flujo del objetivo de transición tiene una entrega).

Grupos de rutas

Cuando compilas un agente, puedes encontrar que muchas páginas tienen un conjunto común de rutas. Para hacer que las rutas sean reutilizables, puedes definir grupos de rutas. Estos grupos son un recurso para todo el flujo.

Por ejemplo, es posible que desees que tu flujo maneje la entrada del usuario final, como “Quiero agregar un complemento a mi pizza” y “Quiero cambiar el tamaño de mi bebida”. Estas entradas deben manejarse cuando alguna de las páginas del flujo esté activa. Puedes definir dos rutas con intents a fin de manejar estas entradas para todas las páginas relevantes, pero esto es mucho trabajo duplicado. En su lugar, puedes definir el grupo de rutas una vez y agregar una referencia al grupo en todas las páginas relevantes.

Rutas a nivel de flujo

Las rutas a nivel de flujo son rutas que se aplican a un flujo si las agregas a la página de inicio del flujo. Estos tipos de controladores tienen los siguientes casos de uso:

X Elemento
Son controladores con un requisito de condición o de intent dentro del alcance de la página de inicio del flujo.
Son controladores con un requisito de intent dentro del alcance de todas las páginas dentro del flujo.

Para crear rutas a nivel de flujo desde la consola, sigue estos pasos:

  1. Abre la página de inicio del flujo.
  2. Haz clic en el botón Agregar en el encabezado Rutas.
  3. Se abrirá el panel de edición de rutas.
  4. Proporciona los campos de ruta.
  5. Haz clic en Guardar.

Para reordenar las rutas a nivel de flujo desde la consola, haz lo siguiente:

  1. Abre la página de inicio del flujo.
  2. Haz clic en el encabezado Rutas.
  3. Se abrirá el panel de la lista de rutas.
  4. Arrastra las rutas en el orden deseado. Como alternativa, haz clic en el menú de opciones y selecciona Mover a.

Para borrar rutas a nivel de flujo de la consola, sigue estos pasos:

  1. Abre la página de inicio del flujo.
  2. Haz clic en el encabezado Rutas.
  3. Se abrirá el panel de la lista de rutas.
  4. Haz clic en el menú de opciones .
  5. Selecciona Borrar.

Rutas a nivel de página

Las rutas a nivel de página son rutas que se aplican a una página. Estos tipos de controladores tienen los siguientes casos de uso:

X Item
Son controladores con un requisito de condición o de intent dentro del alcance cuando las páginas específicas están activas.

Para crear rutas a nivel de página desde la consola, haz lo siguiente:

  1. Abre la página (no la página de inicio del flujo).
  2. Haz clic en el botón Agregar en el encabezado Rutas.
  3. Se abrirá el panel de edición de rutas.
  4. Proporciona los campos de ruta.
  5. Haz clic en Guardar.

Para reordenar las rutas a nivel de página desde la consola, sigue estos pasos:

  1. Abre la página (no la página de inicio del flujo).
  2. Haz clic en el encabezado Rutas.
  3. Se abrirá el panel de la lista de rutas.
  4. Arrastra las rutas en el orden deseado. Como alternativa, haz clic en el menú de opciones y selecciona Mover a.

Para borrar rutas a nivel de la página de la consola, haz lo siguiente:

  1. Abre la página (no la página de inicio del flujo).
  2. Haz clic en el encabezado Rutas.
  3. Se abrirá el panel de la lista de rutas.
  4. Haz clic en el menú de opciones .
  5. Selecciona Borrar.

Controladores de eventos

Los controladores de eventos tienen un requisito para ser llamados:

Término Definición
Requisito del evento Es un evento que se debe invocar. Los eventos se identifican por su nombre. Algunos eventos integrados se invocan cuando se recibe una entrada inesperada del usuario final o cuando se produce un error de webhook. También puedes definir eventos personalizados que invocas cuando algo suceda fuera de la conversación.

Puedes aplicar controladores de eventos a los flujos (controladores de eventos a nivel de flujo), a las páginas (controladores de eventos a nivel de la página) y a los parámetros (controladores de eventos a nivel de parámetros). Por ejemplo, puedes usar controladores de eventos en las siguientes situaciones:

X Elemento
Cuando la entrada del usuario final no coincide con ningún intent, un controlador de eventos sin coincidencias proporciona una respuesta de entrega estática específica.
Un cronómetro vence en tu sistema y deseas proporcionar información de recordatorio al usuario final con una respuesta de entrega estática específica.

Controladores de eventos a nivel de flujo

Los controladores de eventos a nivel de flujo son controladores de eventos que se aplican a un flujo. Estos tipos de controladores tienen los siguientes casos de uso:

X Elemento
Son controladores con un requisito de evento dentro del alcance de la página de inicio del flujo.
Son controladores con un requisito de evento dentro del alcance de todas las páginas dentro del flujo.
Control de entradas de usuario final inesperadas que se comparten por todas las páginas de un flujo
Control de errores de webhook que comparten por todas las páginas de un flujo.
Control los eventos personalizados que invoca tu sistema y que comparten todas las páginas de un flujo.

Cada flujo tiene controladores de eventos para los eventos integrados no-match y no-input. Estos controladores de eventos se crean automáticamente cuando creas un flujo y no se pueden borrar.

Para crear controladores de eventos a nivel de flujo desde la consola, haz lo siguiente:

  1. Abre la página de inicio del flujo.
  2. Haz clic en el botón para agregar en el encabezado Controladores de eventos.
  3. Se abrirá el panel del controlador de eventos.
  4. Proporciona los campos del controlador de eventos.
  5. Haz clic en Guardar.

Para borrar los controladores de eventos a nivel de flujo de la consola, haz lo siguiente:

  1. Abre la página de inicio del flujo.
  2. Haz clic en el encabezado Controladores de eventos.
  3. Se abrirá el panel de lista de controladores de eventos.
  4. Coloca el cursor sobre un controlador de eventos y, luego, haz clic en el botón Borrar .

Controladores de eventos a nivel de página

Los controladores de eventos a nivel de página son controladores de eventos que se aplican a una página. Estos tipos de controladores tienen los siguientes casos de uso:

X Item
Son controladores con un requisito de evento dentro del alcance cuando hay páginas específicas activas.
Control de entradas de usuarios finales inesperadas, específicas de una página
Control de errores de webhook, específicos de una página.
Control de eventos personalizados que invoca tu sistema, específicos de una página.

Para crear controladores de eventos a nivel de la página desde la consola, haz lo siguiente:

  1. Abre una página (no la página de inicio del flujo).
  2. Si no hay un encabezado Controladores de eventos, haz clic en Agregar controlador de estado, selecciona Controladores de eventos y, luego, haz clic en Aplicar.
  3. Haz clic en el botón para agregar en el encabezado Controladores de eventos.
  4. Se abrirá el panel del controlador de eventos.
  5. Proporciona los campos del controlador de eventos.
  6. Haz clic en Guardar.

Para borrar controladores de eventos a nivel de la página de la consola, haz lo siguiente:

  1. Abre una página (no la página de inicio del flujo).
  2. Haz clic en el encabezado Controladores de eventos.
  3. Se abrirá el panel de lista de controladores de eventos.
  4. Coloca el cursor sobre un controlador de eventos y, luego, haz clic en el botón Borrar .

Controladores de eventos a nivel de parámetros

Los controladores de eventos a nivel de parámetros son controladores que se aplican a un parámetro de formulario. También se los conoce como controladores de solicitudes nuevas. Estos controladores de eventos no permiten eventos personalizados, ya que están diseñados, en particular, para manejar entradas de usuario final no válidas cuando se completan formularios.

Estos tipos de controladores tienen los siguientes casos de uso:

X Item
El usuario final no proporcionó una entrada válida cuando se le solicitó completar un parámetro de formulario.

Para crear controladores de eventos a nivel de parámetros desde la consola, haz lo siguiente:

  1. Abre una página que contenga los parámetros del formulario.
  2. Haz clic en un parámetro.
  3. Se abrirá el panel de parámetros.
  4. Desplázate hacia abajo hasta la sección Volver a enviar controladores de eventos y haz clic en Agregar controlador de eventos.
  5. Se abrirá el panel del controlador de eventos.
  6. Proporciona los campos del controlador de eventos.
  7. Haz clic en Guardar.

Para borrar los controladores de eventos a nivel de parámetros de la consola, haz lo siguiente:

  1. Abre una página que contenga los parámetros del formulario.
  2. Haz clic en un parámetro.
  3. Se abrirá el panel de parámetros.
  4. Desplázate hacia abajo hasta la sección Controladores de eventos de repetición.
  5. Coloca el cursor sobre un controlador de eventos y, luego, haz clic en el botón Borrar .

Eventos integrados

Los siguientes eventos están integrados y Dialogflow los invoca. Algunos eventos están restringidos a ciertos niveles.

Nombre del evento
Nivel del flujo Nivel de página Nivel de parámetros Cuando se invoca
sys.no-match-default
  • En el nivel de flow o page: la entrada del usuario final no coincide con ningún intent para los controladores que están dentro del alcance.
  • En el nivel de parameter, la entrada del usuario final no cumple con el parámetro del formulario.
sys.no-match-[1-6] Si proporcionas controladores para cualquiera de estos eventos ordenados de manera forma, se invocan en lugar de sys.no-match-default y en orden: sys.no-match-1, sys.no-match-2, …
sys.no-input-default No se recibió la entrada del usuario final. Se puede invocar en los siguientes casos:
  • Dialogflow recibe una entrada de texto del usuario final vacía.
  • Dialogflow recibe una entrada de audio del usuario final vacía o la entrada no contiene ninguna voz reconocida.
  • Ocurre un sin tiempo de espera de voz antes de que la entrada de audio del usuario final contenga cualquier voz reconocida.
sys.no-input-[1-6] Si proporcionas controladores para cualquiera de estos eventos ordenados de manera forma, se invocan en lugar de sys.no-input-default y en orden: sys.no-input-1, sys.no-input-2, …
sys.invalid-parameter Se invoca cuando una respuesta de webhook invalida el parámetro configurando WebhookResponse.pageInfo.formInfo.parameterInfo.state en INVALID.
sys.long-utterance La entrada del usuario final excede la longitud máxima permitida (256 caracteres). Si no se proporciona, Dialogflow trata la declaración de usuario larga como no-match.
webhook.error La llamada de webhook mostró un error. Este evento solo se invoca: 1) si no hay un controlador de eventos de webhook detallado (p.ej., webhook.error.timeout) que coincida con el código de error de webhook, 2) si no hay un objetivo de transición establecido en la ruta original que llamó a la entrega con el webhook con errores. Consulta la sección Pedido de evaluación para obtener más detalles.
webhook.error.timeout Se agotó el tiempo de espera de la llamada de webhook. Un evento de webhook solo se invocará si no se estableció ningún objetivo de transición en la ruta original que llamó a la entrega con el webhook con errores. Consulta la sección Pedido de evaluación para obtener más detalles.
webhook.error.bad-request El webhook mostró 400 Bad Request. Un evento de webhook solo se invocará si no se estableció ningún objetivo de transición en la ruta original que llamó a la entrega con el webhook con errores. Consulta la sección Pedido de evaluación para obtener más detalles.
webhook.error.rejected El webhook mostró 401 Authorized o 403 Forbidden. Un evento de webhook solo se invocará si no se estableció ningún objetivo de transición en la ruta original que llamó a la entrega con el webhook con errores. Consulta la sección Pedido de evaluación para obtener más detalles.
webhook.error.unavailable El webhook mostró 503 Service Unavailable. Un evento de webhook solo se invocará si no se estableció ningún objetivo de transición en la ruta original que llamó a la entrega con el webhook con errores. Consulta la sección Pedido de evaluación para obtener más detalles.
webhook.error.not-found La llamada de webhook falló porque no se pudo acceder a la URL de webhook. Un evento de webhook solo se invocará si no se estableció ningún objetivo de transición en la ruta original que llamó a la entrega con el webhook con errores. Consulta la sección Pedido de evaluación para obtener más detalles.

Los siguientes eventos están integrados y los invocas tú. Consulta la sección Eventos personalizados para obtener instrucciones sobre cómo invocar eventos.

Nombre del evento
Descripción
WELCOME Este evento se usa en la situación especial en la que el agente inicia la conversación. En general, esto solo es necesario para los usuarios de Dialogflow que implementan integraciones de telefonía. Si invocas este evento, se establece la coincidencia con el intent de bienvenida.

Eventos personalizados

Puedes crear eventos personalizados y controladores de eventos. Los eventos personalizados se usan para controlar lo que ocurre fuera de la conversación con el usuario final. Por ejemplo, el usuario final hizo clic en un botón, pasó una cierta cantidad de tiempo, cambió el inventario disponible durante la conversación, y así sucesivamente.

Los eventos se identifican de forma sencilla por nombre. No uses nombres de eventos que comiencen con sys. o webhook. para evitar conflictos con eventos integrados.

A fin de invocar un evento con la API, consulta el campo queryInput.event del método detectIntent para el tipo Session.

Selecciona un protocolo y una versión para la referencia de sesión:

Protocolo V3 V3beta1
REST Recurso de sesión Recurso de sesión
RPC Interfaz de sesión Interfaz de sesión
C++ SessionsClient No disponible
C# SessionsClient No disponible
Go SessionsClient No disponible
Java SessionsClient SessionsClient
Node.js SessionsClient SessionsClient
PHP No disponible No disponible
Python SessionsClient SessionsClient
Ruby No disponible No disponible

Orden de evaluación

Los controladores se evalúan en un orden específico. Se aplican las siguientes reglas generales:

  1. Solo se evalúan los controladores dentro del alcance.
  2. Solo se puede llamar a los controladores cuyos requisitos se cumplen.
  3. Si se llama a un controlador sin un objetivo de transición, la evaluación de la lista de controladores continúa. Debido a esta regla, varias entregas pueden agregar varios mensajes a la cola de respuestas.
  4. Si se llama a un controlador con un objetivo de transición, finaliza la evaluación de la lista de controladores.
  5. Si se llama a un controlador con entregas, y la entrega da como resultado un error de webhook:
    • Si el controlador tiene un objetivo de transición definido, el webhook falla silenciosamente.
    • Si un controlador de eventos está dentro del alcance del evento, controla el evento y la evaluación de la lista de controladores.
    • Si ningún controlador de eventos está dentro del alcance del evento, el webhook falla en silencio.
  6. Cuando se satisface un requisito de intent, este se consume, por lo que solo se puede llamar al primer controlador de ruta que se encuentra para el intent (consulta Propagación de intents para ver las excepciones).
  7. Cuando se cumple un requisito de condición, no se consume la condición, por lo que se pueden llamar a varias rutas con la condición.
  8. Cuando se cumple un requisito de evento, se consume el evento, por lo que solo se puede llamar al primer controlador de eventos que se encontró para el evento.
  9. La pila de llamadas del controlador puede afectar el orden de evaluación.

La evaluación consta de tres fases:

  1. Las rutas que tienen un requisito de intent se evalúan en este orden:
    1. Nivel de página: Son rutas individuales aplicadas a la página actual, en el orden proporcionado.
    2. Grupos a nivel de página: Son grupos de rutas aplicados a la página actual, en el orden proporcionado.
    3. Nivel de flujo: Son rutas aplicadas al flujo activo, en el orden proporcionado.
    4. Grupos de nivel de flujo: Son grupos de ruta aplicados al flujo activo en el orden proporcionado.
  2. Las rutas que solo tienen un requisito de condición se evalúan en el siguiente orden:
    1. Nivel de página: Son rutas individuales aplicadas a la página actual, en el orden proporcionado.
    2. Grupos a nivel de página: Son grupos de rutas aplicados a la página actual, en el orden proporcionado.
    3. Nivel de flujo (solo si la página actual es la página de inicio del flujo).: Rutas que se aplican al flujo activo, en el orden proporcionado.
    4. Grupos a nivel de flujo (solo si la página actual es la página de inicio de flujo): Grupos de rutas aplicados al flujo activo, en el orden proporcionado.
  3. Los controladores de eventos se evalúan en este orden:
    1. Nivel de parámetro: Los controladores de eventos aplicados al parámetro de formulario de la página actual que el agente intenta completar (controladores de solicitud nuevas) en el orden proporcionado.
    2. Nivel de página: controladores de eventos aplicados a la página actual, en el orden proporcionado.
    3. Nivel de flujo: Los controladores de eventos aplicados al flujo activo, en el orden proporcionado.

Objetivos simbólicos de transición

Cuando ingresas un objetivo de transición para un controlador, puedes ingresar flujos o páginas específicos, pero también puedes ingresar objetivos simbólicos de transición:

Objetivo simbólico de transición
Descripción
START_PAGE Transición a la página de inicio del flujo activo con nombre similar.
END_FLOW Finaliza el flujo activo actual y vuelve a la página que generó la transición al flujo actual. Consulta también la Pila de llamadas del controlador.
END_SESSION Borra la sesión actual y pasa a la página especial llamada END_SESSION. La siguiente entrada de usuario reiniciará la sesión en la página de inicio del Flujo de inicio predeterminado.
PREVIOUS_PAGE Transición a la página anterior que causó la transición a la página actual El estado de la página anterior se restablecerá después de la transición.
CURRENT_PAGE Vuelve la transición a la página actual. Esto puede ser útil si deseas que el agente repita algo.

Pila de llamadas del controlador

Cuando una sesión pasa a END_FLOW, vuelve a la página de llamada que causó una transición al flujo completado. En este caso, se conserva la pila de llamadas del controlador. Se omitirán todos los controladores que se evaluaron antes desde la página de llamada y el resto de los controladores se evaluarán en orden.

Por ejemplo:

  1. La página P tiene tres controladores en este orden: H1, H2 y H3.
  2. Se evalúa H1, pero no provoca una transición.
  3. Se evalúa H2 y provoca una transición al flujo F.
  4. Una página en el flujo F pasa a END_FLOW.
  5. La sesión regresa a la página P, que se vuelve a activar con un estado preservado.
  6. La evaluación del controlador en la página P continúa desde el estado que conservó y, por lo tanto, se evalúa H3.

Establece condiciones

Para configurar las condiciones con la consola, proporciona reglas de condición con una de las tres opciones lógicas:

  • Coincide con AL MENOS UNA de las reglas del índice (OR)
  • Coincide con TODAS las reglas (AND)
  • Personalizar expresión

Para tu comodidad, puedes usar las opciones O a fin de crear condiciones simples o compuestas para los valores de los parámetros.

Puedes usar la opción de forma gratuita Personaliza la expresión para todos los tipos de condiciones, incluidas las funciones del sistema y las constantes booleanas.

Por ejemplo, para establecer una condición que tenga un 10% de probabilidades de aprobar la evaluación, selecciona la opción Personaliza la expresión e ingresa $sys.func.rand() < 0.1 el campo Condición:

Captura de pantalla de la configuración de una condición personalizada