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

Esta seção descreve 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 comunica com o Dialogflow por meio do próprio formato de webhook padrão, em vez do Formato do webhook de conversa do Actions on Google. O formato de webhook do Dialogflow contém todas as informações do formato de webhook de conversa com outros dados específicos do Dialogflow, como informações sobre contextos e parâmetros.

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

Corpo da solicitação

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

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

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

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

{
  "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 Dialogflow webhook, 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 de ajuda

O snippet abaixo mostra um exemplo de resultado auxiliar no formato webhook do Dialogflow. Este exemplo mostra a resposta do usuário depois que o webhook indica ao Google Assistente que ele precisa 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 de 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 o formato de webhook do Dialogflow.

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

Campos-chave para "google" payload são resumidos abaixo:

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

No ExpectedIntent objeto, você especifica estes valores:

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

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

A lista a seguir resume as strings de especificação de valor para auxiliares que você pode definir em um systemIntent para uma resposta do webhook do Dialogflow. Para acessar uma lista completa de intents do Actions on Google, para controle da conversa, consulte a 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 para uma pergunta do tipo 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 app Android.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Recupera 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 o local exato.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Solicita um fluxo de vinculação de contas para associar a conta de um usuário.

Exemplo de resposta simples

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

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

Exemplo de auxiliar

O snippet abaixo mostra um exemplo de como usar uma intent auxiliar no Dialogflow webhook. Neste exemplo, o webhook usa a intent auxiliar actions.intent.OPTIONS para instruir o Google Assistente a receber uma seleção do 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 Assistente assume a conversa e solicita que o usuário faça uma seleção com base no as opções fornecidas. Ao coletar todas as entradas necessárias do usuário, o Assistente envia esse resultado auxiliar de volta ao fulfillment em uma solicitação do 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 conversa sessão no formato webhook do Dialogflow. O expectUserResponse O valor de false na mensagem de resposta envia sinais ao Google Assistente que nenhuma outra entrada do usuário é esperada e que isso deve encerrar o conversa.

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

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