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.