Intents integrados (Dialogflow)

Un intent integrado es un identificador único que puedes especificar para indicarle a Asistente de Google que tu Acción puede entregar una categoría específica de solicitudes de usuarios. Por ejemplo, estos son algunos ejemplos de consultas de los usuarios que el Asistente hace coincidir con intents integrados:

  • Intent integrado"Jugar": "Hey Google, Juega a un juego de memoria"
  • Intent integrado"Obtener horóscopo": "Ok Google. Obtén mi horóscopo"

Durante el descubrimiento de acciones, Asistente puede usar metadatos sobre tu Acción, incluidos los intents integrados que especificaste, para recomendarla a los usuarios. Para minimizar los recorridos de ida y vuelta conversacionales, Asistente también intenta analizar los parámetros de las consultas de los usuarios y pasarlos a tu acción.

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

Cómo integrar intents integrados

Según cómo compiles tu acción, existen diferentes maneras de integrar intents integrados.

Dialogflow

Si usas Dialogflow para crear tu acción, puedes adjuntar un intent integrado gráficamente 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 Intents.

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

    Figura 1: Agrega un evento de Dialogflow en 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: Adjunta 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 en 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 de nombre en tu definición de Action.
  2. Sube tu paquete de acciones a tu proyecto de acciones con la herramienta gactions, como se describe en 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, tu entrega puede recibir parámetros adicionales. El esquema del intent define los nombres de los parámetros y sus tipos como tipos primitivos o entidades de schema.org. Para ver el esquema de los intents integrados de las acciones de conversación, consulta la referencia de intents integrados.

Los parámetros para intents integrados son opcionales. Asistente se encarga de completar los parámetros con valores si se pueden extraer de la invocación del intent integrado por parte 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 Es un valor de cadena.
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 con el mensaje "What's the air Quality in San Francisco tomorrow?" (¿Cuál será 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 para "San Francisco".
  • El parámetro temporalCoverage contiene el valor schema.org/Duration para la fecha de mañana en relación 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 incluía 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.

});

Prueba 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 a un juego”.
  3. Busca tu Acción en el diálogo de selección de apps que se muestra.
  4. Selecciona tu app para enviarle un intent.
Figura 3: El diálogo de selección de acciones que resulta
de una frase de intent integrada.
Figura 4: 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 activa tu Acción, envía al usuario al intent y la funcionalidad específicos de la acción con la menor fricción posible. Por ejemplo, si tu Acción admite el intent integrado PLAY_GAME y recibe ese intent, debes enviar inmediatamente al usuario a la función del juego de tu Acción. Evita volver a preguntarle al usuario si quiere jugar.
  • Control de parámetros de intents integrados: Asegúrate de usar los valores de parámetros de intents integrados que Asistente envía a tu entrega. Evita volver a solicitar esos valores al usuario.