Intents integrados (Dialogflow)

Un intent integrado es un identificador único que puedes especificar para indicarle al Asistente de Google que tu acción puede cumplir con una categoría específica de solicitudes de usuarios. Por ejemplo, a continuación, se muestran algunos ejemplos de consultas del usuario que hace coincidir Asistente con intents integrados:

  • Intent integrado de"Jugar": "Ok Google. Juega a un juego de memoria"
  • "Intent de obtener horóscopo" integrado: "Ok Google. Obtener mi horóscopo"

Durante el descubrimiento de acciones, Asistente puede usar metadatos sobre tu acción, incluidos los intents integrados que hayas especificado, para recomendar tu acción a los usuarios. Para minimizar los recorridos de ida y vuelta en conversaciones, el Asistente también intenta analizar parámetros de las consultas del usuario y pasarlos a tu acción.

Para ver la lista completa de intents integrados que admite Asistente, incluidos sus parámetros y consultas de usuario de ejemplo, consulta la referencia de intents integrados.

Cómo integrar intents integrados

Según cómo compiles la acción, habrá diferentes maneras de integrar intents integrados.

Dialogflow

Si usas Dialogflow para crear tu acción, puedes adjuntar un intent integrado de forma gráfica desde la consola de Dialogflow.

Para adjuntar un intent integrado con Dialogflow, sigue estos pasos:

  1. Abre la consola de Dialogflow, selecciona tu agente y, luego, navega a la pantalla de Intents.

  2. Crea o selecciona el intent que activa el agente cuando recibe un intent integrado específico. Abre la sección Eventos y haz clic en Agregar evento.

    Figura 1: Agregar un evento de Dialogflow a la consola de Dialogflow

  3. En el campo Eventos, escribe el nombre de un evento de intent integrado para tu agente (por ejemplo, actions_intent_PLAY_GAME).

    Figura 2: Adjuntar un intent integrado a tu agente en la consola de Dialogflow

  4. Haz clic en Guardar.

SDK de Actions

Si usas el SDK de Actions para compilar tu acción, debes especificar la asignación entre los intents integrados y las acciones de tu paquete de acciones.

Para adjuntar un intent integrado con el SDK de Actions, sigue estos pasos:

  1. Especifica el intent integrado en el campo del nombre en la definición de Acción.
  2. Sube tu paquete de acciones a tu proyecto de acciones con la herramienta gactions, como se describe en la descripción general del SDK de Actions.

Por ejemplo, en el siguiente fragmento, se muestra cómo puedes agregar el intent integrado CHECK_AIR_QUALITY:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

Cómo controlar parámetros de intents integrados

Cuando tu acción se invoca a través de un intent integrado, es posible que tu entrega reciba parámetros adicionales. El esquema del intent define los nombres de los parámetros y sus tipos como entidades primitivas o entidades de schema.org. Para ver el esquema de intents integrados de acciones de conversación, consulta la referencia de intents integrados.

Los parámetros para los intents integrados son opcionales. Asistente controla el llenado de parámetros con valores si se pueden extraer desde la invocación del intent integrado del usuario.

Por ejemplo, el esquema del intent integrado actions.intent.CHECK_AIR_QUALITY define cuatro parámetros opcionales:

Nombre del parámetro Tipo
attributes Un valor de string.
location Un objeto schema.org/Place.
temporalCoverage Un objeto schema.org/Duration.
timeIndicator Una EnumeratedDuration (extensión específica de Google)

En el siguiente fragmento de código, se muestra un ejemplo de la solicitud de webhook de conversación (JSON) cuando un usuario invoca tu acción diciendo "¿Cuál es la calidad del aire en San Francisco mañana?":

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

En este ejemplo, los parámetros toman los siguientes valores:

  • El parámetro location contiene el valor schema.org/Place de “San Francisco”.
  • El parámetro temporalCoverage contiene el valor schema.org/Duration para la fecha de mañana relacionada con la hora de la invocación.
  • No hay valores para los parámetros attributes y timeIndicator porque la frase de invocación del usuario no incluyó esa información.

Si usas la biblioteca cliente de Actions on Google para Node.js, puedes recuperar el valor de los parámetros como se muestra en el siguiente fragmento:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

Cómo probar integraciones con intents integrados

Sigue estos pasos para probar tu integración:

  1. Abre el simulador de Actions con tu Acción de prueba habilitada o abre Asistente en tu dispositivo.
  2. Di o escribe una consulta asociada con ese intent integrado. Por ejemplo, "Quiero jugar un juego".
  3. En el diálogo de selección de apps que se muestra, busca tu acción.
  4. Selecciona tu app para enviarle un intent.
Figura 3. El diálogo de selección de acciones que genera
a partir de una frase de intent integrada.
Figura 4: Cómo invocar una acción adjunta a un intent integrado

Prácticas recomendadas para usar intents integrados

Debes seguir estas prácticas recomendadas cuando uses intents integrados:

  • Asignar intents integrados a acciones específicas: Cuando un intent integrado específico active tu acción, envía al usuario a ese intent y funcionalidad específicos con la menor fricción posible. Por ejemplo, si tu acción admite el intent integrado PLAY_GAME y recibe ese intent, debes enviar al usuario de inmediato a la función del juego de tu acción. Evita preguntar de nuevo al usuario si quiere jugar.
  • Controla los parámetros de intents integrados: Asegúrate de usar los valores de parámetros de intents integrados que Asistente envía a la entrega. Evita volver a solicitar al usuario esos valores.