Formato do webhook do Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

Nesta seção, descrevemos o formato do payload JSON quando o Actions on Google invoca seu fulfillment usando o Dialogflow v2.

Se você estiver usando o Dialogflow para criar ações, o fulfillment se comunicará com o Dialogflow por meio do próprio formato de webhook padrão, em vez do formato de webhook de conversa do Actions on Google. O formato do webhook do Dialogflow contém todas as informações do formato do webhook de conversa, além de outros dados específicos do Dialogflow, como informações sobre contextos e parâmetros.

Para mais exemplos de mensagens JSON para webhooks do Dialogflow, consulte este projeto do GitHub.

Corpo da solicitação

A mensagem de request do Dialogflow contém dados no formato de webhook do Dialogflow. Esse objeto inclui informações específicas do Actions on Google, conforme resumido abaixo:

  • O valor de originalDetectIntentRequest.source é "google".
  • O originalDetectIntentRequest.version indica a versão da solicitação no Actions on Google.
  • O originalDetectIntentRequest.payload contém informações importantes específicas das Actions on Google, incluindo o JSON de solicitação de conversa do Google Assistente.
  • O campo Conversation.conversationToken não é compatível com as solicitações de webhook do Dialogflow. Em vez disso, o fulfillment pode usar um contexto do Dialogflow para manter os dados durante a vida útil da conversa.

Exemplo de solicitação de invocação simples

O snippet abaixo mostra um exemplo de uma solicitação de invocação no formato de webhook do Dialogflow.

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Exemplo de solicitação de conversa simples

O snippet abaixo mostra um exemplo de solicitação de conversa no formato de webhook do Dialogflow, em que a entrada do usuário é uma string de texto.

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Exemplo de resultado auxiliar

O snippet abaixo mostra um exemplo de um resultado auxiliar no formato de webhook do Dialogflow. Este exemplo mostra a resposta do usuário depois que o webhook indica ao Google Assistente que é necessário receber a confirmação do usuário.

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Corpo da resposta

O Content-Type no cabeçalho das postagens HTTP do endpoint de fulfillment para o Google Assistente precisa ser application/json.

A mensagem de resposta que o fulfillment envia para o Dialogflow precisa estar no formato do webhook do Dialogflow.

Ao se comunicar com o Google Assistente, sua resposta normalmente contém um objeto payload que encapsula um objeto "google". O objeto de payload "google" inclui informações específicas do Actions on Google. Ele precisa conter, no mínimo, um campo expectUserResponse e um richResponse ou systemIntent.

Os campos-chave do objeto de payload "google" estão resumidos abaixo:

Campo Descrição
expectUserResponse Indica se o fulfillment espera uma resposta do usuário. Defina o valor como true quando continuar a conversa e false para encerrá-la.
userStorage Armazena dados persistentes vinculados a um usuário específico. A quantidade total de armazenamento é de 10.000 bytes.
richResponse Esse campo contém áudio, texto, cards, sugestões ou dados estruturados para o Google Assistente renderizar. Para saber mais sobre o uso de respostas avançadas para o Actions on Google, consulte Respostas avançadas.
systemIntent Esse campo tem a mesma estrutura de ExpectedInput.possibleIntents. Sua resposta normalmente vai conter um systemIntent se o fulfillment estiver usando uma intent auxiliar. O campo possibleIntents em systemIntent precisa ser definido como um objeto ExpectedIntent, com o nome do campo inputValueData alterado para data.

No objeto ExpectedIntent, especifique estes valores:

  • intent: um nome de intent para o auxiliar que indica o tipo de informação que você quer que o usuário forneça.
  • data: uma especificação de valor, que é uma string que descreve os dados necessários para o Google Assistente realizar o auxiliar.

Por exemplo, se você estiver solicitando a permissão do usuário, defina intent como actions.intent.PERMISSSION e data como a especificação de valor como "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", além dos campos desse tipo.

A lista a seguir resume as strings de especificação de valor para auxiliares que podem ser definidos em um systemIntent para uma resposta do webhook do Dialogflow. Para conferir uma lista completa das intents do Actions on Google para controle de conversa, consulte a referência Intents.

Nome da intent Nome do evento do Dialogflow Especificação de valor Descrição
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Recebe uma confirmação do usuário (por exemplo, uma resposta a uma pergunta de sim ou não).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Recebe uma entrada de data e hora do usuário.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Recebe uma entrada de endereço de entrega do usuário.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Solicita um fluxo de link direto para um aplicativo Android.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Recebe o item selecionado de uma interface de lista ou carrossel.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Extrai as informações do usuário, incluindo nome completo, localização aproximada ou localização exata.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Solicita um fluxo para vincular a conta de um usuário.

Exemplo de resposta simples

O snippet abaixo mostra um exemplo de resposta simples no formato de webhook do Dialogflow.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

Exemplo de ajuda

O snippet abaixo mostra um exemplo de uso de uma intent auxiliar no formato de webhook do Dialogflow. Neste exemplo, o webhook está usando a intent auxiliar actions.intent.OPTIONS para instruir o Google Assistente a acessar uma seleção de usuário entre duas opções.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

Ao receber a mensagem do exemplo anterior, o Google Assistente assume temporariamente o controle da conversa e solicita que o usuário faça uma seleção com base nas opções oferecidas. Ao coletar todas as entradas necessárias do usuário, o Google Assistente envia esse resultado auxiliar de volta ao fulfillment em uma solicitação de webhook do Dialogflow.

O snippet abaixo mostra um exemplo do resultado auxiliar com a seleção de escolha do usuário.

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Exemplo de encerramento de conversa

O snippet abaixo mostra um exemplo de resposta simples para encerrar uma sessão de conversa no formato do webhook do Dialogflow. O valor expectUserResponse de false na mensagem de resposta sinaliza ao Google Assistente que nenhuma outra entrada do usuário é esperada e que a conversa atual precisa ser encerrada.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

Para saber como substituir o comportamento padrão quando os usuários invocam uma frase padrão para encerrar uma conversa com o Google Assistente, consulte o guia de saídas da conversa.