Intents integradas (Dialogflow)

Uma intent integrada é um identificador exclusivo que você pode especificar para informar ao Google Assistente que sua ação pode atender a uma categoria específica de solicitações do usuário. Confira alguns exemplos de consultas do usuário que o Google Assistente faz a correspondência com intents integradas:

  • Intenção integrada"Jogar": "Ok Google. Divirta-se com um jogo de memória"
  • Intent integrada"Get horoscope": "Ok Google. Ver meu horóscopo"

Durante a descoberta de ações, o Google Assistente pode usar metadados sobre a ação, incluindo as intents integradas especificadas, para recomendar sua ação aos usuários. Para minimizar as idas e vindas da conversa, o Google Assistente também tenta verificar os parâmetros das consultas do usuário e transmiti-los para a ação.

Para conferir a lista completa de intents integradas com suporte do Google Assistente, incluindo parâmetros e exemplos de consultas do usuário, consulte a Referência de intents integradas.

Integrar intents integradas

Dependendo de como você está criando a Ação, há diferentes maneiras de integrar intents integradas.

Dialogflow

Se você estiver usando o Dialogflow para criar sua ação, poderá anexar uma intent integrada graficamente pelo console do Dialogflow.

Para anexar uma intent integrada ao Dialogflow, siga estas etapas:

  1. Abra o console do Dialogflow, selecione seu agente e navegue até a tela Intents.
  2. Crie ou selecione a intent que o agente aciona quando recebe uma intent integrada específica. Abra a seção Eventos e clique em Adicionar evento.

    Figura 1. Adicionar um evento do Dialogflow no console.
  3. No campo Eventos, digite o nome de um evento de intent integrada para seu agente (por exemplo, actions_intent_PLAY_GAME).

    Figura 2. Como anexar uma intent integrada ao seu agente no console do Dialogflow.
  4. Clique em Salvar.

SDK do Actions

Se você estiver usando o SDK do Actions para criar sua ação, precisará especificar o mapeamento entre as intents integradas e as ações no pacote.

Para anexar uma intent integrada com o SDK do Actions, siga estas etapas:

  1. Especifique a intent integrada no campo de nome da definição de Action.
  2. Faça upload do pacote de ações para o projeto do Actions usando a ferramenta gactions, conforme descrito em Visão geral do SDK do Actions.

Por exemplo, o snippet a seguir mostra como adicionar a intent integrada 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
      }
   }
}

Processar parâmetros de intent integrada

Quando a ação é invocada por uma intent integrada, o fulfillment pode receber outros parâmetros. O esquema de intent define os nomes e os tipos dos parâmetros como tipos primitivos ou entidades do schema.org (link em inglês). Para conferir o esquema de intents integradas de ações de conversa, consulte a Referência de intents integradas.

Os parâmetros para intents integradas são opcionais. O Google Assistente processará o preenchimento dos parâmetros com valores se eles puderem ser extraídos da invocação da intent integrada pelo usuário.

Por exemplo, o esquema da intent integrada actions.intent.CHECK_AIR_QUALITY define quatro parâmetros opcionais:

Nome do parâmetro Tipo
attributes Um valor de string.
location Um objeto schema.org/Place.
temporalCoverage Um objeto schema.org/Duration.
timeIndicator Uma EnumeratedDuration (extensão específica do Google).

O snippet de código a seguir mostra um exemplo da solicitação de webhook de conversa (JSON) quando um usuário invoca sua ação dizendo "Qual é a qualidade do ar em São Francisco amanhã?":

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

Neste exemplo, os parâmetros usam os seguintes valores:

  • O parâmetro location contém o valor schema.org/Place para "São Francisco".
  • O parâmetro temporalCoverage contém o valor schema.org/Duration para a data de amanhã em relação ao horário da invocação.
  • Não há valores para os parâmetros attributes e timeIndicator, porque a frase de invocação do usuário não incluía essas informações.

Se você usar a biblioteca de cliente do Actions on Google para Node.js, poderá recuperar o valor dos parâmetros conforme mostrado no snippet a seguir:

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.

});

Testar integrações com intents integradas

Siga estas etapas para testar sua integração:

  1. Abra o simulador do Actions com a ação de teste ativada ou abra o Google Assistente no seu dispositivo.
  2. Fale ou digite uma consulta associada a essa intent integrada. Por exemplo, "Quero jogar".
  3. Na caixa de diálogo de seleção de app exibida, encontre a ação.
  4. Selecione seu app para enviar uma intent a ele.
Figura 3. A caixa de diálogo de seleção "Ação" resultante
de uma frase de intent integrada.
Figura 4. Invocar uma ação anexada a uma intent integrada.

Práticas recomendadas para usar intents integradas

Siga estas práticas recomendadas ao usar intents integradas:

  • Mapear intents integradas para ações específicas: quando uma intent integrada específica acionar sua Ação, direcione o usuário à intent e funcionalidade específicas dela com o mínimo de atrito possível. Por exemplo, se a ação oferecer suporte à intent integrada PLAY_GAME e receber essa intent, encaminhe o usuário imediatamente para o recurso do jogo da sua ação. Evite perguntar novamente se o usuário quer jogar.
  • Processar parâmetros de intent integrada: use os valores de parâmetro de intent integrados que o Google Assistente envia para o fulfillment. Evite solicitar novamente esses valores ao usuário.