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.