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

Ta sekcja opisuje format ładunku JSON, gdy Actions on Google wywołuje Twoją w usłudze 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 zamiast Format webhooka rozmowy w Actions on Google. Format webhooka Dialogflow zawiera wszystkie informacje format webhooka rozmowy wraz z dodatkowymi danymi dotyczącymi Dialogflow, takimi jak informacje kontekstów i parametrów.

Więcej przykładów wiadomości JSON dla webhooków Dialogflow znajdziesz w dokumentacji w tym projekcie GitHub.

Uwaga: w przypadku agentów Dialogflow korzystających z interfejsu API w wersji 2 i włączonych funkcji w wersji beta wartości atrybutów session i outputContexts.name będą zaczynać się od projects/${PROJECTID}/agent/environments/${ENVID}/users/${USERID}/sessions/${SESSIONID}. (W Dialogflow 2 bez włączonej funkcji beta rozpoczyna się od projects/${PROJECTID}/agent/sessions/${SESSIONID}).

Treść żądania

Prośba od Dialogflow zawiera dane w formacie webhooka Dialogflow. Ten obiekt zawiera: Podsumowanie informacji dotyczących Actions on Google:

• Wartość originalDetectIntentRequest.source to „google”.
• originalDetectIntentRequest.version oznacza działanie w Actions on Google wersję dla żądania.
• originalDetectIntentRequest.payload zawiera kluczowe działania w Actions on Google informacje, w tym rozmowę; prośba JSON z Asystenta.
• Pole Conversation.conversationToken nie jest obsługiwane przez webhooka Dialogflow żądań. Zamiast tego Twoja realizacja może korzystać z Dialogflow kontekstu, aby utrwalać dane w całym długość rozmowy.

Przykład prostego żądania wywołania

Poniższy fragment kodu zawiera przykład żądania wywołania w Dialogflow webhooka.

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

Poniższy fragment kodu zawiera przykład żądania rozmowy w Dialogflow webhooka, gdzie dane wejściowe użytkownika to ciąg tekstowy.

{
  "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ładowy wynik pomocniczy w formacie webhooka Dialogflow. Ten przykład pokazuje odpowiedź użytkownika po tym, jak webhook powiadomi 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.

Wiadomość z odpowiedzią wysyłana do Dialogflow musi zostać wysłana przez Twoją realizację format webhooka Dialogflow.

Gdy komunikujesz się z Asystentem, odpowiedź zwykle zawiera obiekt payload, który zawiera obiekt „google”. Obiekt ładunku „google” zawiera działania dotyczące informacji związanych z Google. Musi zawierać, co najmniej expectUserResponse i richResponse lub systemIntent.

Kluczowe pola obiektu „google” podsumowujemy obiekt ładunku:

Pole	Opis
expectUserResponse	Wskazuje, czy realizacja oczekuje odpowiedzi użytkownika. Ustaw wartość na true, kiedy kontynuować rozmowę, a false, aby ją zakończyć. rozmowę.
userStorage	Przechowuje dane trwałe powiązane z określonym użytkownikiem. Łączna ilość miejsca na dane wynosi 10 000 bajtów.
richResponse	To pole zawiera dźwięk, tekst, karty, sugestie lub uporządkowane dane które ma wykonać Asystent. Aby dowiedzieć się więcej o używaniu odpowiedzi rozszerzonych w przypadku Actions on Google, zobacz Rozszerzone odpowiedzi
systemIntent	To pole ma taką samą strukturę jak ExpectedInput.possibleIntents Odpowiedź zwykle zawiera systemIntent, jeśli usługa korzysta z intencji pomocniczej. Pole possibleIntents w obiekcie systemIntent musi być ustawione na obiekt ExpectedIntent, a nazwa pola inputValueData musi zostać zmieniona na data.

W ciągu: ExpectedIntent możesz określić te wartości:

• intent: nazwa intencji dla pomocnika, która wskazuje typ informacji, które użytkownik ma podać, oraz
• data: specyfikacja wartości, czyli ciąg tekstowy opisujący dane niezbędna, by Asystent wyprowadził pomoc.

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

Poniższa lista zawiera podsumowanie ciągów specyfikacji wartości dla elementów pomocniczych, które można ustawić w systemIntent dla odpowiedzi webhooka Dialogflow. Pełną listę intencji Actions on Google dla kontroli konwersacyjnej, zobacz Dokumentacja 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 (na przykład odpowiedź na pytanie typu „tak” lub „nie”).
actions.intent.DATETIME	actions_intent_DATETIME	"@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec"	Uzyskuje dane wejściowe użytkownika dotyczące daty i godziny.
actions.intent.DELIVERY_ADDRESS	actions_intent_DELIVERY_ADDRESS	"@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec"	Uzyskuje adres dostawy podany od użytkownika.
actions.intent.LINK	actions_intent_LINK	"@type": "type.googleapis.com/google.actions.v2.LinkValueSpec"	Pyta o przepływ 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"	Pobiera informacje o użytkowniku, w tym imię i nazwisko, przybliżoną lokalizację lub dokładną lokalizację.
actions.intent.SIGN_IN	actions_intent_SIGN_IN	"@type": "type.googleapis.com/google.actions.v2.SignInValueSpec"	prosi o przeprowadzenie procesu łączenia kont w celu połączenia konta użytkownika.

Przykład prostej odpowiedzi

Poniższy fragment kodu zawiera przykładową prostą odpowiedź w Dialogflow webhooka.

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

Przykład Asystenta

Fragment kodu poniżej pokazuje przykład użycia intencji pomocniczej w Dialogflow webhooka. W tym przykładzie webhook używa zamierzenia pomocniczego actions.intent.OPTIONS, aby zlecić Asystentowi uzyskanie wyboru użytkownika spośród 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 otrzymaniu wiadomości z poprzedniego przykładu Asystent tymczasowo przejmuje kontrolę nad rozmową i zachęca użytkownika do dokonania wyboru na podstawie podanych opcji. Po zebraniu wszystkich wymaganych danych wejściowych użytkownika Asystent wysyła ten wynik pomocniczy z powrotem do Twojej realizacji w żądaniu webhooka Dialogflow.

Fragment kodu poniżej zawiera przykładowy wynik pomocniczy z wyborem opcji 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 kończenia rozmowy

Fragment kodu poniżej to przykład prostej odpowiedzi na zakończenie rozmowy w formacie webhooka Dialogflow. expectUserResponse wartość false w komunikacie z odpowiedzią, która jest sygnalizowana Asystentowi że użytkownik nie powinien podejmować dalszych działań i powinien zakończyć rozmowy.

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

Informacje o zastępowaniu domyślnego działania, gdy użytkownicy wywołują standardowe działanie aby zakończyć rozmowę z Asystentem, zobacz przewodnika po wyjściach z rozmowy.