Format webhooka Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

W tej sekcji opisano format ładunku JSON, gdy Actions on Google wywołuje Twoją realizację za pomocą Dialogflow w wersji 2.

Jeśli do tworzenia akcji używasz Dialogflow, Twoja realizacja komunikuje się z Dialogflow za pomocą własnego, standardowego formatu webhooka, a nie przez format webhooka rozmowy w Actions on Google. Format webhooka Dialogflow zawiera wszystkie informacje o formacie webhooka rozmowy oraz dodatkowe dane specyficzne dla Dialogflow, takie jak informacje o kontekstach i parametrach.

Więcej przykładów wiadomości JSON dotyczących webhooków Dialogflow znajdziesz w tym projekcie w GitHubie.

Treść żądania

Komunikat żądania z Dialogflow zawiera dane w formacie webhooka Dialogflow. Ten obiekt zawiera informacje charakterystyczne dla działań w Google. Oto podsumowanie:

  • Wartość originalDetectIntentRequest.source to „google”.
  • originalDetectIntentRequest.version wskazuje wersję w Actions on Google odpowiadającą danemu żądaniu.
  • originalDetectIntentRequest.payload zawiera kluczowe informacje specyficzne dla Google, w tym żądanie JSON dotyczące rozmowy od Asystenta.
  • Pole Conversation.conversationToken nie jest obsługiwane w żądaniach webhooka Dialogflow. Zamiast tego realizacja może korzystać z kontekstu Dialogflow do przechowywania danych przez cały czas trwania rozmowy.

Przykład prostego żądania wywołania

Fragment kodu poniżej zawiera przykład żądania wywołania w formacie webhooka 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}"
}

Przykład prostej prośby o rozmowę

Fragment kodu poniżej zawiera przykład żądania rozmowy w formacie webhooka Dialogflow, w którym dane wejściowe użytkownika są ciągiem tekstowym.

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

Przykład wyniku pomocniczego

Poniższy fragment kodu zawiera przykład wyniku pomocniczego w formacie webhooka Dialogflow. Ten przykład pokazuje odpowiedź użytkownika po tym, jak webhook poinformuje Asystenta, że musi uzyskać potwierdzenie użytkownika.

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

Treść odpowiedzi

Content-Type w nagłówku postów HTTP z punktu końcowego realizacji do Asystenta musi mieć wartość application/json.

Odpowiedź, którą Twoja realizacja wysyła do Dialogflow, musi mieć format webhooka Dialogflow.

Gdy komunikujesz się z Asystentem, odpowiedź zwykle zawiera obiekt payload otoczony obiektem „google”. Obiekt ładunku „google” zawiera informacje specyficzne dla Google. Musi zawierać co najmniej pole expectUserResponse oraz pole richResponse lub systemIntent.

Poniżej znajdziesz podsumowanie najważniejszych pól obiektu ładunku „google”:

Pole Opis
expectUserResponse Wskazuje, czy realizacja oczekuje odpowiedzi użytkownika. Ustaw wartość true, aby kontynuować rozmowę, i false, aby ją zakończyć.
userStorage Przechowuje trwałe dane powiązane z określonym użytkownikiem. Łączna ilość miejsca na dane to 10 000 bajtów.
richResponse To pole zawiera dźwięk, tekst, karty, sugestie lub uporządkowane dane, które Asystent może renderować. Więcej informacji o używaniu odpowiedzi z elementami rozszerzonymi w Actions on Google znajdziesz w artykule o odpowiedziach z elementami rozszerzonymi
systemIntent To pole ma taką samą strukturę jak ExpectedInput.possibleIntents. Jeśli realizacja używa intencji pomocniczej, odpowiedź zwykle zawiera element systemIntent. Pole possibleIntents w systemIntent musi być ustawione na obiekt ExpectedIntent, a nazwa pola inputValueData zmieniona na data.

W obiekcie ExpectedIntent określasz te wartości:

  • intent: nazwa intencji funkcji pomocniczej wskazująca typ informacji, które użytkownik ma podać.
  • data: specyfikacja wartości, czyli ciąg znaków opisujący dane wymagane, aby Asystent wykonał zadanie pomocnicze.

Jeśli na przykład pytasz o zgodę użytkownika, ustaw intent na actions.intent.PERMISSSION, a data w specyfikacji wartości na "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" oraz na pola odpowiednie dla tego typu.

Poniższa lista zawiera podsumowanie ciągów specyfikacji wartości przeznaczonych dla pomocników, które można ustawić w systemIntent dla odpowiedzi webhooka Dialogflow. Pełną listę intencji w Actions on Google dotyczących kontroli konwersacyjnej znajdziesz w dokumentacji intencji.

Nazwa intencji Nazwa zdarzenia Dialogflow Specyfikacja wartości Opis
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Uzyskuje potwierdzenie od użytkownika (np. odpowiedź na pytanie „tak lub nie”).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Pobiera od użytkownika datę i godzinę.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Pobiera od użytkownika adres dostawy.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Prosi o przekazanie precyzyjnego linku do aplikacji na Androida.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Pobiera wybrany element z interfejsu listy lub karuzeli.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Uzyskuje informacje o użytkowniku, takie jak imię i nazwisko, przybliżoną lub dokładną lokalizację.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Prosi o wykonanie procedury łączenia kont w celu połączenia konta użytkownika.

Przykład prostej odpowiedzi

Poniższy fragment kodu zawiera przykład prostej odpowiedzi w formacie webhooka Dialogflow.

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

Przykład aplikacji pomocniczej

Fragment kodu poniżej zawiera przykład użycia intencji pomocniczej w formacie webhooka Dialogflow. W tym przykładzie webhook korzysta z intencji pomocniczej actions.intent.OPTIONS, aby przekazać Asystentowi instrukcję pobierania użytkownika z jednej z 2 opcji.

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

Po odebraniu wiadomości z poprzedniego przykładu Asystent tymczasowo przejmuje rozmowę i prosi użytkownika o dokonanie wyboru na podstawie podanych opcji. Po zebraniu wszystkich wymaganych danych wejściowych użytkownika Asystent odsyła ten wynik pomocniczy z powrotem do realizacji w żądaniu webhooka Dialogflow.

Fragment kodu poniżej pokazuje przykład wyniku pomocniczego z wyborem użytkownika.

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

Przykład strony Zakończ rozmowę

Fragment kodu poniżej zawiera przykład prostej odpowiedzi na zakończenie sesji w formacie webhooka Dialogflow. Wartość expectUserResponse parametru false w wiadomości z odpowiedzią informuje Asystenta, że żadne dalsze działania użytkownika nie są oczekiwane i że powinna zakończyć bieżącą rozmowę.

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

Informacje o zastępowaniu domyślnego działania, gdy użytkownicy wywołują standardowe wyrażenie w celu zakończenia rozmowy z Asystentem, znajdziesz w przewodniku po wyjściu z rozmowy.